This article answers frequently asked questions about the mssql-django Django backend for SQL Server, Azure SQL Database, Azure SQL Managed Instance, and SQL database in Microsoft Fabric.
General
What is mssql-django?
The mssql-django package is a Microsoft-maintained Django database backend for SQL Server. It allows Django applications to connect to SQL Server, Azure SQL Database, Azure SQL Managed Instance, and SQL database in Microsoft Fabric. Version 2.0 and later versions connect through either the pyodbc driver, which is the default, or Microsoft's mssql-python driver.
Install it with pip:
pip install mssql-django
What versions of Django does mssql-django support?
The mssql-django package version 2.0 supports Django 5.2, 6.0, and 6.1. Projects on Django 3.2 through 5.1 stay on version 1.8.0. Check the support lifecycle for the full compatibility matrix.
What versions of Python are supported?
The mssql-django package version 2.0 supports Python 3.10 through 3.14. The specific Python version must also be compatible with your Django version: Django 5.2 is tested with Python 3.10 through 3.13, and Django 6.0 and 6.1 are tested with Python 3.12 through 3.14. See Support lifecycle for the full compatibility matrix.
Which Python database driver does mssql-django use?
Version 2.0 and later versions support two drivers, selected for each database alias. pyodbc is the default and needs an externally installed Microsoft ODBC Driver for SQL Server. To use Microsoft's mssql-python driver instead, which needs no separate ODBC driver install, add python_driver to that alias's OPTIONS dictionary:
"OPTIONS": {
"python_driver": "mssql_python",
},
Aliases that omit the option keep using pyodbc. For the behavior differences between the two paths, see Select the database driver for mssql-django.
Is mssql-django maintained by Microsoft?
Configuration
What ENGINE value do I use in settings.py?
Set ENGINE to "mssql" in your DATABASES configuration:
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"HOST": "<your-server>",
},
}
Which ODBC driver should I use?
On the default pyodbc path, use Microsoft ODBC Driver 18 for SQL Server. It's the default, and the backend automatically falls back to ODBC Driver 17 if version 18 isn't installed. Specify the driver explicitly in the OPTIONS dictionary only if you need to pin a specific version, which also turns off the fallback:
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
},
The mssql-python path ignores the driver option and uses the ODBC Driver 18 that pip installs with it.
How do I connect to Azure SQL Database?
Use the fully qualified server name with port 1433:
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<your-database>",
"USER": "<your-username>",
"PASSWORD": "<your-password>",
"HOST": "<your-server>.database.windows.net",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
},
},
}
How do I use Microsoft Entra authentication?
Use extra_params in OPTIONS or the TOKEN setting. The TOKEN setting works with any azure.identity credential, including DefaultAzureCredential and ManagedIdentityCredential.
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token
"TOKEN": token,
See Microsoft Entra authentication for all supported methods.
Features
Does mssql-django support JSONField?
Yes, JSONField is supported on SQL Server 2016 and later. JSON data is stored as nvarchar(max) and queried using SQL Server's JSON functions. See JSONField support for supported lookups and limitations.
Does mssql-django support time zone-aware datetimes?
Yes. When USE_TZ=True, Django uses the datetimeoffset data type in SQL Server. If you're migrating an existing database, you need to alter existing datetime2 columns. See Time zone support.
Can I call stored procedures?
Yes. Use connection.cursor() with cursor.execute() to call stored procedures. See Stored procedures for examples including multiple parameters and result sets.
Does bulk_create return IDs?
By default, no. The return_rows_bulk_insert option defaults to False. Set it to True in your database OPTIONS to enable returning IDs after bulk insert. This option must remain False for tables with triggers. See Bulk operations.
Troubleshooting
I get "ODBC Driver not found." How do I fix it?
Install the Microsoft ODBC Driver for SQL Server. On Linux, add the Microsoft APT repository first and then install the driver:
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -fsSL https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
ACCEPT_EULA=Y sudo apt-get install -y msodbcsql18
On Windows, download the installer from the Microsoft website. On macOS, use Homebrew:
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18
See Installation for complete platform-specific instructions.
Why does my migration fail with "Cannot alter IDENTITY column"?
SQL Server doesn't support altering a column to or from an IDENTITY (AutoField) column. Create a new model with the desired field type and migrate data manually. See Limitations and unsupported features in mssql-django.
Why does bulk_update fail with nullable fields?
The backend handles all-NULL updates automatically. If you need to control the placeholder value, use the default parameter in bulk_update, which keeps NULL out of CASE WHEN ... THEN NULL expressions that cause SQL Server type inference errors:
Product.objects.bulk_update(products, ["description"], default="")
See Bulk operations for details.