Use Microsoft SQL Server With Django in Production

Problem statement

Your organization's data lives in Microsoft SQL Server or Azure SQL Database, and the Django app must use it. Django does not include a SQL Server backend, but Microsoft maintains mssql-django, which connects through ODBC. Getting it into production means installing Microsoft's ODBC driver on Linux or in Docker, configuring encryption and authentication, and understanding where SQL Server differs from PostgreSQL in Django features.

1. pip install mssql-django (it brings pyodbc), matching the version to your Django release.
2. Install Microsoft ODBC Driver 18 for SQL Server on the server or in the image.
3. Set ENGINE = "mssql" and OPTIONS = {"driver": "ODBC Driver 18 for SQL Server"}.
4. Keep encryption on (Driver 18 encrypts by default) and trust a proper certificate, or set TrustServerCertificate only for internal test servers.
5. Run the full migration history and test suite against SQL Server before going live.

Step-by-step solution

1. Install the ODBC driver

On Debian or Ubuntu images, add Microsoft's package repository and install the driver plus unixODBC headers:

FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends curl gnupg2 unixodbc-dev \
 && curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft.gpg \
 && echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" \
    > /etc/apt/sources.list.d/mssql-release.list \
 && apt-get update && ACCEPT_EULA=Y apt-get install -y msodbcsql18 \
 && rm -rf /var/lib/apt/lists/*

Adjust the repository path to your base image's Debian or Ubuntu release. On Windows, the driver installer is separate.

2. Configure Django

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "shop",
        "USER": "shopapp",
        "PASSWORD": os.environ["DB_PASSWORD"],
        "HOST": "shop-sql.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes;TrustServerCertificate=no",
        },
        "CONN_MAX_AGE": 60,
    }
}

Azure SQL also supports Microsoft Entra authentication; with the right extra_params (for example Authentication=ActiveDirectoryMsi), an Azure-hosted app can connect with its managed identity.

3. Encryption and certificates

ODBC Driver 18 sets Encrypt=yes by default and verifies the server certificate. Azure SQL has trusted certificates, so verification works. On-premises servers with self-signed certificates fail with "SSL Provider: certificate verify failed"; install a proper certificate on SQL Server rather than setting TrustServerCertificate=yes in production.

4. Collation, Unicode, and migrations

Django CharField and TextField map to nvarchar columns, which store Unicode. Database collation determines case sensitivity: the common default SQL_Latin1_General_CP1_CI_AS is case-insensitive, so username uniqueness and __exact lookups ignore case, unlike PostgreSQL. Decide whether that is acceptable or choose a case-sensitive collation at database creation. Run migrations against a test database and look for warnings about unsupported operations.

5. Know the limitations

Check mssql-django's documentation for the version you use. Common differences:

• No support for some django.contrib.postgres features (naturally) and limited JSON querying on older SQL Server versions.
• Constraints on nullable unique fields are implemented with filtered indexes.
• Very large IN lists can hit SQL Server's parameter limit (2,100 parameters per statement); batch them.

Explanation

mssql-django is a Django database backend maintained by Microsoft that translates ORM queries into T-SQL and executes them through pyodbc. pyodbc in turn relies on the ODBC driver manager (unixODBC on Linux) and Microsoft's ODBC driver to speak the TDS protocol to SQL Server. Each layer must be present, which is why installation is more involved than for PostgreSQL. Once connected, most Django features work, with differences driven by SQL Server's collation rules and T-SQL limits.

Edge cases / notes

• Connection pooling. ODBC driver pooling is separate from Django's CONN_MAX_AGE; use CONN_MAX_AGE and leave driver pooling at defaults unless you have a reason.
• ARM images. Microsoft publishes the driver for arm64 on recent distributions; check availability for your base image.
• Legacy schemas. For existing databases, inspectdb generates models; mark them managed = False if another system owns the schema.

Next steps

• Hosting on Windows? See Deploy Django on Windows IIS.
• Azure hosting with Deploy Django on Azure App Service.
• Building the image: Dockerize Django for Production.

FAQ

Does Django support SQL Server?

Through the Microsoft-maintained mssql-django backend, not in Django core.

Which ODBC driver should I use?

ODBC Driver 18 for SQL Server, the current Microsoft driver.

Why does my connection fail with a certificate error?

Driver 18 encrypts and verifies certificates by default. Install a trusted certificate on the server.

Are string comparisons case-sensitive on SQL Server?

It depends on the collation. The common default is case-insensitive.