{"id":2929,"library":"django-mysql","title":"Django-MySQL","description":"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.","status":"active","version":"4.19.0","language":"en","source_language":"en","source_url":"https://github.com/adamchainz/django-mysql","tags":["django","mysql","mariadb","database","orm","fields"],"install":[{"cmd":"pip install django-mysql","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Django extension library and requires a compatible Django version to function.","package":"Django","optional":false},{"reason":"Django-MySQL requires a compatible MySQL database driver for Django, such as mysqlclient or PyMySQL.","package":"mysqlclient","optional":true}],"imports":[{"note":"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.","wrong":"from django.db.models import JSONField","symbol":"JSONField","correct":"from django_mysql.models import JSONField"},{"symbol":"ListField","correct":"from django_mysql.models import ListField"},{"symbol":"SetField","correct":"from django_mysql.models import SetField"},{"symbol":"SizedBinaryField","correct":"from django_mysql.models import SizedBinaryField"},{"symbol":"MySQLQuerySet","correct":"from django_mysql.query import MySQLQuerySet"},{"note":"Calling this function is optional; simply adding 'django_mysql' to INSTALLED_APPS automatically registers the checks.","symbol":"register_checks","correct":"from django_mysql.checks import register_checks"}],"quickstart":{"code":"import os\nfrom django.conf import settings\nfrom django.apps import apps\n\nif not apps.ready:\n    settings.configure(\n        INSTALLED_APPS=[\n            'django.contrib.auth',\n            'django.contrib.contenttypes',\n            'django_mysql',\n            'myapp' # Assuming your models are in 'myapp'\n        ],\n        DATABASES={\n            'default': {\n                'ENGINE': 'django.db.backends.mysql',\n                'NAME': 'mydatabase',\n                'USER': os.environ.get('MYSQL_USER', 'root'),\n                'PASSWORD': os.environ.get('MYSQL_PASSWORD', ''),\n                'HOST': os.environ.get('MYSQL_HOST', 'localhost'),\n                'PORT': os.environ.get('MYSQL_PORT', '3306'),\n                'OPTIONS': {\n                    'init_command': \"SET sql_mode='STRICT_TRANS_TABLES'\",\n                }\n            }\n        },\n        DEFAULT_AUTO_FIELD='django.db.models.BigAutoField',\n        TIME_ZONE='UTC',\n        USE_TZ=True,\n    )\n    apps.populate(settings.INSTALLED_APPS)\n\nfrom django.db import models\nfrom django_mysql.models import JSONField\n\n# Define a simple Django model using Django-MySQL's JSONField\nclass MyModel(models.Model):\n    name = models.CharField(max_length=100)\n    data = JSONField(default=dict)\n\n    def __str__(self):\n        return self.name\n\n# This code snippet would typically be followed by:\n# python manage.py makemigrations myapp\n# python manage.py migrate\n# And then interactive usage:\n# from myapp.models import MyModel\n# instance = MyModel.objects.create(name='Sample Item', data={'version': 1, 'items': ['a', 'b']})\n# print(f\"Created: {instance.name} with data {instance.data}\")\n# instance.data['status'] = 'processed'\n# instance.save()\n# print(f\"Updated: {instance.name} with data {instance.data}\")\n\nprint(\"Django-MySQL model definition with JSONField is ready.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All major versions (e.g., 3.x to 4.x), particularly during Django or Python major version updates."},{"fix":"Ensure that `'django_mysql'` is present in your `INSTALLED_APPS` list in your Django project's `settings.py` file.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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+.","severity":"breaking","affected_versions":"<3.0 to >=3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}