Django-MySQL

4.19.0 · active · verified Sat Apr 11

Django-MySQL extends Django's built-in MySQL and MariaDB support to leverage their specific features not available on other databases. It provides custom fields (like JSONField, ListField), aggregates, lookups, and system checks. The library is actively maintained with releases often aligned with new Django major versions, ensuring compatibility and continued feature development.

Warnings

breaking Django-MySQL has strict compatibility requirements with specific Django and Python versions. Upgrading Django or Python without checking `django-mysql`'s release notes can lead to compatibility errors.
Fix: Always consult the official `django-mysql` documentation and changelog for Python and Django compatibility before upgrading either library. For version 4.19.0, Python >= 3.9 and Django >= 3.2 are required.
gotcha Forgetting to add `'django_mysql'` to your `INSTALLED_APPS` in `settings.py` will prevent many features from working correctly, including the automatic registration of system checks.
Fix: Ensure that `'django_mysql'` is present in your `INSTALLED_APPS` list in your Django project's `settings.py` file.
breaking Prior to django-mysql 3.0, `JSONField` stored JSON as `TEXT`. From 3.0 onwards (Django 3.1+), it uses the native `JSON` column type for MySQL 5.7.8+ or MariaDB 10.2.3+.
Fix: If upgrading from an older version where `JSONField` was used and you were not using a native JSON column, you may need a data migration to convert your existing `TEXT` data to the native `JSON` type. Refer to the `django-mysql` 3.0 release notes for migration strategies.
gotcha Fields like `ListField` and `SetField` store Python lists/sets as serialized strings (VARCHAR/TEXT) in the database. While convenient, querying based on values *within* these lists/sets will not use database indexes efficiently and can lead to performance issues on large datasets.
Fix: For efficient querying of individual elements, consider normalizing your data into a separate many-to-many relationship or using `django_mysql.models.JSONField` with native JSON functions (if your MySQL version supports them) for structured data.

Install

pip install django-mysql Install latest version

Imports

JSONField
```
from django_mysql.models import JSONField
```
Django's native JSONField works for PostgreSQL and MySQL 8+ with specific settings. django-mysql's JSONField provides broader compatibility for MySQL versions and additional features.

ListField

from django_mysql.models import ListField

SetField

from django_mysql.models import SetField

SizedBinaryField

from django_mysql.models import SizedBinaryField

MySQLQuerySet

from django_mysql.query import MySQLQuerySet

register_checks
```
from django_mysql.checks import register_checks
```
Calling this function is optional; simply adding 'django_mysql' to INSTALLED_APPS automatically registers the checks.

Quickstart

To quickly get started with Django-MySQL, first ensure you have a MySQL/MariaDB database configured in your Django settings. Add 'django_mysql' to your `INSTALLED_APPS`. This example demonstrates defining a model with a `django_mysql.models.JSONField` which provides native JSON support for MySQL. After defining your models, run `makemigrations` and `migrate` to apply the database schema changes. Note: For a runnable example, ensure your `settings.py` includes `INSTALLED_APPS` and `DATABASES` configurations, and substitute 'myapp' with the actual name of your Django app containing the model.

import os
from django.conf import settings
from django.apps import apps

if not apps.ready:
    settings.configure(
        INSTALLED_APPS=[
            'django.contrib.auth',
            'django.contrib.contenttypes',
            'django_mysql',
            'myapp' # Assuming your models are in 'myapp'
        ],
        DATABASES={
            'default': {
                'ENGINE': 'django.db.backends.mysql',
                'NAME': 'mydatabase',
                'USER': os.environ.get('MYSQL_USER', 'root'),
                'PASSWORD': os.environ.get('MYSQL_PASSWORD', ''),
                'HOST': os.environ.get('MYSQL_HOST', 'localhost'),
                'PORT': os.environ.get('MYSQL_PORT', '3306'),
                'OPTIONS': {
                    'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
                }
            }
        },
        DEFAULT_AUTO_FIELD='django.db.models.BigAutoField',
        TIME_ZONE='UTC',
        USE_TZ=True,
    )
    apps.populate(settings.INSTALLED_APPS)

from django.db import models
from django_mysql.models import JSONField

# Define a simple Django model using Django-MySQL's JSONField
class MyModel(models.Model):
    name = models.CharField(max_length=100)
    data = JSONField(default=dict)

    def __str__(self):
        return self.name

# This code snippet would typically be followed by:
# python manage.py makemigrations myapp
# python manage.py migrate
# And then interactive usage:
# from myapp.models import MyModel
# instance = MyModel.objects.create(name='Sample Item', data={'version': 1, 'items': ['a', 'b']})
# print(f"Created: {instance.name} with data {instance.data}")
# instance.data['status'] = 'processed'
# instance.save()
# print(f"Updated: {instance.name} with data {instance.data}")

print("Django-MySQL model definition with JSONField is ready.")

view raw JSON →