{"id":7434,"library":"mssql-django","title":"Microsoft SQL Server Django Backend","description":"mssql-django is the official Microsoft-supported Django database backend for Microsoft SQL Server, Azure SQL, and SQL Database in Microsoft Fabric. It provides robust database connectivity for the Django web framework. The library is actively maintained with frequent releases, currently at version 1.7, offering broad compatibility with recent Django and Python versions.","status":"active","version":"1.7","language":"en","source_language":"en","source_url":"https://github.com/microsoft/mssql-django","tags":["django","sql-server","azure-sql","database","backend","microsoft","odbc"],"install":[{"cmd":"pip install mssql-django","lang":"bash","label":"Install mssql-django"}],"dependencies":[{"reason":"Core dependency for a Django database backend, automatically installed.","package":"Django","optional":false},{"reason":"Required for Python ODBC connectivity to SQL Server, automatically installed.","package":"pyodbc","optional":false},{"reason":"Required for timezone support, automatically installed.","package":"pytz","optional":false},{"reason":"External system dependency, must be installed separately for pyodbc to function.","package":"Microsoft ODBC Driver for SQL Server","optional":false}],"imports":[{"note":"The correct ENGINE string for mssql-django is 'mssql'. 'sql_server.pyodbc' was used by older, community-maintained predecessors like django-mssql-backend.","wrong":"'ENGINE': 'sql_server.pyodbc'","symbol":"ENGINE setting","correct":"DATABASES = {\n    'default': {\n        'ENGINE': 'mssql',\n        # ... other settings\n    }\n}"}],"quickstart":{"code":"import os\n\nDATABASES = {\n    'default': {\n        'ENGINE': 'mssql',\n        'NAME': 'your_database_name',\n        'USER': os.environ.get('DB_USER', 'your_db_user'),\n        'PASSWORD': os.environ.get('DB_PASSWORD', 'your_db_password'),\n        'HOST': os.environ.get('DB_HOST', 'your_server.database.windows.net'),\n        'PORT': os.environ.get('DB_PORT', ''), # Default port 1433 if empty\n        'OPTIONS': {\n            'driver': os.environ.get('ODBC_DRIVER', 'ODBC Driver 18 for SQL Server'),\n            # 'isolation_level': 'READ UNCOMMITTED', # Example option\n            # 'extra_params': 'Encrypt=yes;TrustServerCertificate=no;', # Example for Azure SQL\n        },\n    }\n}\n\n# Optional: Disable pyodbc's connection pooling\n# DATABASE_CONNECTION_POOLING = False","lang":"python","description":"To use `mssql-django`, configure your Django project's `settings.py` file. The `ENGINE` value must be set to 'mssql'. Ensure your database credentials, host, and an appropriate ODBC driver are specified in the `DATABASES` dictionary. For Azure SQL, additional `extra_params` in `OPTIONS` might be necessary for encryption and certificate trust."},"warnings":[{"fix":"Always check the `mssql-django` release notes or PyPI page for the supported Django and Python versions before upgrading either library. Upgrade `mssql-django` to a version compatible with your Django release.","message":"Django version compatibility is critical. `mssql-django` 1.7 provides full support for Django 6.0, while earlier versions support specific Django releases (e.g., 1.6 for Django 5.1/5.2, 1.4 for Django 5.0). Upgrading your Django version without a compatible `mssql-django` can lead to runtime errors or failed migrations.","severity":"breaking","affected_versions":"< 1.7 with Django 6.0, specific versions for other Django releases"},{"fix":"Upgrade to `mssql-django` 1.6 or newer. For existing migrations, replace `Meta.index_together` with `Meta.indexes` in your models and generate new migrations, then apply them.","message":"Django 5.1 deprecated `Meta.index_together` in favor of `Meta.indexes`. Older `mssql-django` versions (e.g., pre-1.6) or existing migrations using `index_together` with Django 5.1+ can cause `AttributeError` during migrations.","severity":"deprecated","affected_versions":"Django 5.1+ with mssql-django < 1.6"},{"fix":"Refer to the `mssql-django` wiki page on Timezone Support for manual migration steps if upgrading from pre-1.2. For `USE_TZ=True` issues, ensure you are on the latest `mssql-django` version, which includes fixes for `DATETIMEOFFSET` handling.","message":"Timezone support (introduced in v1.2) may require manual migrations for existing `DATETIME` fields, especially if converting to `DATETIMEOFFSET`. There have been known issues with `USE_TZ=True` and `settings.TIME_ZONE != 'UTC'` in versions 1.2 and newer, which were addressed in recent updates.","severity":"gotcha","affected_versions":"1.2 and newer (especially pre-PR #484 fixes)"},{"fix":"Be aware that `UUIDField` will typically map to `char(32)`. If you require `uniqueidentifier`, manual database-level type changes or custom field implementations might be necessary, and ensure thorough testing across `mssql-django` versions around this change.","message":"Native UUID field support was temporarily added in v1.4.1 (mapping to SQL Server `uniqueidentifier`) but reverted in v1.4.2 to restore the original `char(32)` behavior due to internal issues. This can lead to unexpected type mappings or migration failures if you rely on `uniqueidentifier` in `1.4.1` and then downgrade or upgrade past `1.4.2`.","severity":"gotcha","affected_versions":"1.4.1, 1.4.2"},{"fix":"If your application expects rows to be returned after bulk inserts, explicitly set `return_rows_bulk_insert: True` in the `OPTIONS` dictionary of your database configuration. Note that it must be `False` if tables have triggers to avoid insertion failures.","message":"The `return_rows_bulk_insert` option, which controls whether rows are returned after a bulk insert, changed its default to `False` in version 1.2. If you relied on this behavior, or if your tables have triggers, this setting is crucial.","severity":"gotcha","affected_versions":"1.2 and newer"},{"fix":"Download and install the appropriate Microsoft ODBC Driver for SQL Server for your operating system. Ensure the driver name in your Django `OPTIONS` matches the installed driver (e.g., `{'driver': 'ODBC Driver 18 for SQL Server'}`).","message":"A Microsoft ODBC Driver for SQL Server (e.g., 'ODBC Driver 17 for SQL Server' or 'ODBC Driver 18 for SQL Server') must be installed separately on the system where the Django application runs. Without it, `pyodbc` cannot establish a connection.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pip install mssql-django` was successful. In `settings.py`, verify that `ENGINE` is set to `'mssql'` (not `'sql_server.pyodbc'` or other variations).","cause":"The `ENGINE` setting in `settings.py` is incorrect or the `mssql-django` package is not installed or accessible.","error":"'mssql' isn't an available database backend or couldn't be imported."},{"fix":"Upgrade `mssql-django` to version 1.6 or newer. For models, replace `Meta.index_together = [...]` with `Meta.indexes = [models.Index(fields=['field1', 'field2'])]` and run `makemigrations` followed by `migrate`.","cause":"This error occurs when running Django 5.1+ migrations with an older `mssql-django` version (pre-1.6) or with models that still define `Meta.index_together`.","error":"AttributeError: 'Options' object has no attribute 'index_together'."},{"fix":"Check the `mssql-django` documentation or PyPI page for the supported SQL Server versions. Upgrade your SQL Server instance or use an `mssql-django` version that is compatible.","cause":"The version of SQL Server you are connecting to is not supported by the installed `mssql-django` version.","error":"django.db.utils.NotSupportedError: SQL Server vXX is not supported."},{"fix":"1. Verify `HOST` and `PORT` in `settings.py`. For named instances, use `HOST: 'server_ip\\instance_name'` and omit `PORT` or ensure the correct port is specified. 2. Ensure the correct ODBC driver is installed on the system. 3. Check network connectivity and firewall rules on both the client and server. 4. Confirm SQL Server is running and configured to allow remote TCP/IP connections, and SQL Server Browser service is running for named instances.","cause":"A connection to the SQL Server database could not be established. Common reasons include incorrect `HOST` or `PORT`, an incorrect ODBC driver, a firewall blocking the connection, or the SQL Server instance not being configured for remote connections or named instance access.","error":"OperationalError: (pyodbc.Error) ('08001', '[08001] [Microsoft][ODBC Driver 18 for SQL Server]TCP Provider: No connection could be made because the target machine actively refused it.\\r\\n (10061) (SQLDriverConnect); [08001] [Microsoft][ODBC Driver 18 for SQL Server]Login timeout expired (0); [08001] [Microsoft][ODBC Driver 18 for SQL Server]A network-related or instance-specific error has occurred while establishing a connection to SQL Server. Server is not found or not accessible. Check if instance name is correct and if SQL Server is configured to allow remote connections. For SQL Server 2005 onwards see SQL Server Books Online. (10061)')"}]}