Connecting Django to SQL Server: The Official mssql-django Backend Explained

---

Python and Django applications that need SQL Server as their database backend require a connectivity layer that understands both Django’s ORM internals and SQL Server’s SQL dialect. For years that layer was a collection of community forks with inconsistent maintenance and no official Microsoft backing. That changed with the release of mssql-django, the official Microsoft-supported Django backend for SQL Server, Azure SQL Database, and SQL Database in Microsoft Fabric.

This article explains what mssql-django is, why it matters for SQL Server environments running Django applications, what the current 1.7.x release series covers, how to configure it, and what limitations exist as of June 2026. All information is drawn from Microsoft Learn documentation and the official mssql-django GitHub repository.

1 What mssql-django Is Beginner

mssql-django is the official Microsoft-supported database backend for the Django web framework, providing connectivity to SQL Server, Azure SQL Database, Azure SQL Managed Instance, and SQL Database in Microsoft Fabric. It is published by Microsoft on PyPI and maintained on GitHub under the Microsoft organization. The project is open source under the BSD license.

Django communicates with its configured database through a backend: a layer of Python code that translates Django’s ORM operations into database-specific SQL, handles connections through ODBC drivers, and manages schema migrations. Without a SQL Server backend, Django cannot connect to SQL Server at all. mssql-django provides that layer and handles the significant translation work required because SQL Server’s SQL dialect differs from the PostgreSQL and SQLite dialects that Django was designed around.

Key responsibilities of the backend include translating Django ORM queries into T-SQL, managing ODBC connection strings and authentication parameters, handling SQL Server-specific data types, supporting schema migration operations, and maintaining compatibility as both Django and SQL Server release new versions.

2 The History: From Community Forks to Official Backend Beginner

Connecting Django to SQL Server has a long and fragmented history. Before mssql-django, developers used a series of community-maintained packages including django-mssql, django-pyodbc-azure, and django-mssql-backend. These projects provided varying levels of SQL Server support but had no official Microsoft backing and inconsistent maintenance cycles. As Django released new major versions, these backends frequently lagged, leaving teams pinned to older Django versions or unable to use new Django features.

Microsoft released mssql-django as the authoritative replacement, consolidating prior community work under an officially supported and tested product. The package continues the foundational work established by the earlier community packages but is now maintained directly by Microsoft engineering with a defined compatibility policy and active CI testing against supported SQL Server and Django versions.

3 Compatibility Matrix Beginner

The current 1.7.x release series supports a broad range of Django, Python, and SQL Server versions according to Microsoft’s published compatibility data.

Component	Supported Versions	Notes
Django	3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2, 6.0	Django 6.0 requires Python 3.12 or higher
Python	3.8 through 3.14	Python 3.12+ required for Django 6.0
SQL Server	2016 through 2025	SQL Server 2025 added to CI test matrix in 1.7
Azure SQL Database	All current service tiers	Fully supported
Azure SQL Managed Instance	All current configurations	Fully supported
SQL Database in Microsoft Fabric	Current	Engine edition detection fixed in 1.7
ODBC Driver	17 or 18 for SQL Server	Driver 18 is default since 1.7, automatic fallback to 17

4 Installation Beginner

mssql-django is installed from PyPI. Installing the package automatically pulls in Django, pyodbc, and pytz as dependencies.

# Install the current version
pip install mssql-django

# Install a specific version
pip install mssql-django==1.7.3

# Upgrade an existing installation
pip install --upgrade mssql-django

ODBC Driver 18 for SQL Server must also be installed on the host running the Django application. If Driver 18 is not installed, the backend falls back to Driver 17 automatically and logs a warning. Installing ODBC Driver 18 is recommended for new deployments and for environments using Microsoft Entra authentication.

# Verify the installed version after installation
python -c "import mssql; print(mssql.__version__)"

# Check which ODBC drivers are available on the host
# On Windows (run in a Python shell or script)
import pyodbc
print(pyodbc.drivers())

5 Django Settings Configuration Beginner

The database connection is configured in Django’s settings.py file. The ENGINE value must be set to mssql. The following example shows a baseline on-premises SQL Server configuration using Windows authentication.

# settings.py
# Baseline SQL Server configuration using Windows integrated authentication

DATABASES = {
    'default': {
        'ENGINE': 'mssql',
        'NAME':   'YourDatabaseName',
        'HOST':   'YourSQLServerName',     # server name or IP
        'PORT':   '',                       # leave blank for default port 1433
        'OPTIONS': {
            'driver':               'ODBC Driver 18 for SQL Server',
            'trusted_connection':   'yes',  # Windows integrated authentication
            'TrustServerCertificate': 'yes',# required for self-signed certs
        },
    },
}

# Disable pyodbc connection pooling
# Recommended when Django manages its own connection lifecycle
DATABASE_CONNECTION_POOLING = False

# settings.py
# SQL Server with SQL authentication (username and password)

DATABASES = {
    'default': {
        'ENGINE':   'mssql',
        'NAME':     'YourDatabaseName',
        'USER':     'YourSQLLoginName',
        'PASSWORD': 'YourPassword',
        'HOST':     'YourSQLServerName',
        'PORT':     '',
        'OPTIONS': {
            'driver': 'ODBC Driver 18 for SQL Server',
        },
    },
}

DATABASE_CONNECTION_POOLING = False

6 Authentication Options Intermediate

mssql-django supports multiple authentication mechanisms through the OPTIONS dictionary in the database settings. Authentication behavior changed significantly in the 1.7.3 release, which fixed how extra_params authentication settings are parsed.

Windows Integrated Authentication

DATABASES = {
    'default': {
        'ENGINE': 'mssql',
        'NAME':   'YourDatabase',
        'HOST':   'YourServer',
        'PORT':   '',
        'OPTIONS': {
            'driver':             'ODBC Driver 18 for SQL Server',
            'trusted_connection': 'yes',
        },
    },
}

Microsoft Entra (Azure AD) Authentication

# Microsoft Entra password authentication
# Used when connecting to Azure SQL with an Azure AD user account
DATABASES = {
    'default': {
        'ENGINE':   'mssql',
        'NAME':     'YourDatabase',
        'USER':     'user@yourdomain.com',
        'PASSWORD': 'YourPassword',
        'HOST':     'yourserver.database.windows.net',
        'PORT':     '',
        'OPTIONS': {
            'driver':       'ODBC Driver 18 for SQL Server',
            'Authentication': 'ActiveDirectoryPassword',
        },
    },
}

# Microsoft Entra service principal (client credentials)
# Used for application identities in automated pipelines
DATABASES = {
    'default': {
        'ENGINE':   'mssql',
        'NAME':     'YourDatabase',
        'USER':     'YourClientId',
        'PASSWORD': 'YourClientSecret',
        'HOST':     'yourserver.database.windows.net',
        'PORT':     '',
        'OPTIONS': {
            'driver':       'ODBC Driver 18 for SQL Server',
            'Authentication': 'ActiveDirectoryServicePrincipal',
        },
    },
}

7 Azure SQL and Microsoft Fabric Configuration Intermediate

Azure SQL Database, Azure SQL Managed Instance, and SQL Database in Microsoft Fabric use the same mssql engine. The key differences are in the HOST value and authentication method.

# Azure SQL Database
DATABASES = {
    'default': {
        'ENGINE':   'mssql',
        'NAME':     'YourDatabase',
        'USER':     'user@yourserver',
        'PASSWORD': 'YourPassword',
        'HOST':     'yourserver.database.windows.net',
        'PORT':     '',
        'OPTIONS': {
            'driver': 'ODBC Driver 18 for SQL Server',
        },
    },
}

# SQL Database in Microsoft Fabric
# The engine edition detection fix in mssql-django 1.7 is required
# for Fabric SQL Database to work correctly. On earlier versions,
# Fabric's engine edition was misidentified, causing JSONField,
# hash functions, and collation introspection to fail.
DATABASES = {
    'default': {
        'ENGINE':   'mssql',
        'NAME':     'YourFabricDatabase',
        'USER':     'user@yourtenant.onmicrosoft.com',
        'PASSWORD': 'YourPassword',
        'HOST':     'yourworkspace.datawarehouse.fabric.microsoft.com',
        'PORT':     '',
        'OPTIONS': {
            'driver':         'ODBC Driver 18 for SQL Server',
            'Authentication': 'ActiveDirectoryPassword',
        },
    },
}

8 What the 1.7 Series Added Intermediate

The 1.7 release series, spanning from March 2026 through June 2026, represents a significant update to the backend. The changes are documented across three releases from Microsoft.

Version 1.7 (March 2026): Major release

• Full Django 6.0 compatibility including revised query batching, ORDER BY behavior, JSON lookup paths, and db_default support in bulk inserts
• Python 3.14 support added while maintaining compatibility back to Python 3.8 and Django 3.2
• SQL Server 2025 added to the CI test matrix with Linux coverage
• Composite primary key support for Django 5.2 and later, with T-SQL fallback logic for tuple comparisons that SQL Server does not support natively
• Fabric SQL Database engine edition detection fixed
• Default ODBC driver upgraded from version 17 to version 18, with automatic fallback to version 17
• quote_name() fixed for identifiers containing periods
• Meta.indexes no longer dropped during field alterations, fixing a regression that silently removed indexes during schema migrations
• Server properties now fetched in a single database query, eliminating an extra round trip on connection

Version 1.7.2 (May 2026): Timezone and explain fixes

• handle_datetimeoffset now correctly parses the timezone offset from SQL Server’s binary DATETIMEOFFSET representation. Previously, values from DATETIMEOFFSET columns could be returned without their UTC offset, producing naive datetime objects
• Now() now emits SYSDATETIMEOFFSET() when USE_TZ=True is configured, correctly returning timezone-aware timestamps
• QuerySet.explain() fixed for Django 4.0 and later. Django 4.0 changed the internal API for EXPLAIN plans, replacing separate attributes with a single query.explain_info object. The old attribute access caused AttributeError on any queryset using .explain()

Version 1.7.3 (June 2026): Authentication parsing

• Authentication mode now parsed from extra_params using a specification-aligned ODBC parser that correctly handles braced values, embedded semicolons, escaped braces, whitespace, and empty values
• Trusted_Connection and SSPI injection now respect an explicitly configured Authentication= mode, preventing invalid connection string combinations
• Password injection behavior is driven by authentication mode, ensuring password-based modes still receive PWD in the connection string correctly
• DatabaseWrapper subclass cache KeyError edge case resolved

9 Known Limitations Intermediate

Microsoft publishes the following limitations for mssql-django as of the 1.7.x series. These are documented in the official GitHub repository.

Limitation	Detail
AutoField migration	Altering a model field from or to AutoField at migration time is not supported. Schema migrations involving AutoField type changes will fail.
Floating point arithmetic	Floating point arithmetic in some Django annotate functions produces results that differ from other backends due to SQL Server’s floating point handling.
JSONField lookups	JSONField has additional lookup limitations beyond the standard Django JSONField documentation. The project wiki documents the specific lookup types affected.
Tuple lookups with composite PKs	Composite primary key tuple lookups require Django 5.2.4 or later. Earlier Django 5.2 releases lack the required support for full tuple lookup compatibility.
JSONField bulk and CASE WHEN	Some JSONField bulk update and CASE WHEN edge cases have known issues. Specific exclusions are documented in the test suite.
Django 6.0 Python requirement	Django 6.0 requires Python 3.12 or higher. Teams on Python 3.8 through 3.11 cannot use Django 6.0 regardless of the mssql-django version.

10 The ODBC Driver Requirement Beginner

mssql-django uses pyodbc to communicate with SQL Server. pyodbc in turn requires an ODBC driver installed on the host machine. The two supported drivers are ODBC Driver 18 for SQL Server (the current recommended version) and ODBC Driver 17 for SQL Server (the fallback).

Starting with mssql-django 1.7, the backend defaults to ODBC Driver 18. If Driver 18 is not installed, the backend attempts to fall back to Driver 17 automatically and logs a warning. The warning indicates which driver is in use and recommends upgrading to Driver 18 for security improvements.

# Explicitly specify the driver version in Django settings
# Use this to pin a specific driver version rather than relying on the default

DATABASES = {
    'default': {
        'ENGINE': 'mssql',
        'NAME':   'YourDatabase',
        'HOST':   'YourServer',
        'PORT':   '',
        'OPTIONS': {
            'driver': 'ODBC Driver 18 for SQL Server',  # explicit version
        },
    },
}

For SQL Server DBAs supporting Django application teams, confirming which ODBC driver is installed on application servers is a common first diagnostic step when connection problems arise. The ODBC driver version can be verified through Windows ODBC Data Source Administrator on Windows hosts or via the pyodbc.drivers() call in a Python session on any platform.

References

• GitHub: microsoft/mssql-django (official repository, BSD license)
• PyPI: mssql-django (official package, install and compatibility)
• Microsoft Tech Community: mssql-django 1.7 release announcement
• Microsoft Tech Community: mssql-django 1.7.2 release announcement
• Microsoft Tech Community: mssql-django 1.7.3 release announcement
• GitHub: mssql-django release history and changelog
• Microsoft Docs: Download ODBC Driver for SQL Server