Microsoft SQL Server Django Backend

1.7 · active · verified Thu Apr 16

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.

Common errors

```
'mssql' isn't an available database backend or couldn't be imported.
```
cause The `ENGINE` setting in `settings.py` is incorrect or the `mssql-django` package is not installed or accessible.

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).
```
AttributeError: 'Options' object has no attribute 'index_together'.
```
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`.

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`.
```
django.db.utils.NotSupportedError: SQL Server vXX is not supported.
```
cause The version of SQL Server you are connecting to is not supported by the installed `mssql-django` version.

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.
```
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)')
```
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.

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.

Warnings

breaking 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.
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.
deprecated 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.
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.
gotcha 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.
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.
gotcha 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`.
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.
gotcha 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.
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.
gotcha 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.
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'}`).

Install

pip install mssql-django Install mssql-django

Imports

ENGINE setting
wrong:
```
'ENGINE': 'sql_server.pyodbc'
```
correct:
```
DATABASES = {
    'default': {
        'ENGINE': 'mssql',
        # ... other settings
    }
}
```
The correct ENGINE string for mssql-django is 'mssql'. 'sql_server.pyodbc' was used by older, community-maintained predecessors like django-mssql-backend.

Quickstart

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.

import os

DATABASES = {
    'default': {
        'ENGINE': 'mssql',
        'NAME': 'your_database_name',
        'USER': os.environ.get('DB_USER', 'your_db_user'),
        'PASSWORD': os.environ.get('DB_PASSWORD', 'your_db_password'),
        'HOST': os.environ.get('DB_HOST', 'your_server.database.windows.net'),
        'PORT': os.environ.get('DB_PORT', ''), # Default port 1433 if empty
        'OPTIONS': {
            'driver': os.environ.get('ODBC_DRIVER', 'ODBC Driver 18 for SQL Server'),
            # 'isolation_level': 'READ UNCOMMITTED', # Example option
            # 'extra_params': 'Encrypt=yes;TrustServerCertificate=no;', # Example for Azure SQL
        },
    }
}

# Optional: Disable pyodbc's connection pooling
# DATABASE_CONNECTION_POOLING = False

view raw JSON →