Django Backend for Microsoft SQL

mssql-django is the official Microsoft‑supported Django database backend for SQL Server, Azure SQL and SQL Database in Microsoft Fabric.

It provides a reliable, enterprise‑grade database connectivity option for the Django web framework, enabling Python developers to build and run production‑ready applications on Microsoft’s data platform.

This project is the continuation and evolution of earlier community efforts, and it builds on the strong foundation established by django-mssql-backend and its predecessors. mssql-django focuses on long‑term stability, performance, security, and compatibility with both Django and SQL Server.

Supportability

Quick Start

1. Install mssql-django (pulls in Django, pyodbc, and pytz automatically):

   pip install mssql-django
   

2. Configure your settings.py:

DATABASES = {
    'default': {
        'ENGINE': 'mssql',
        'NAME': 'mydb',
        'USER': 'user@myserver',
        'PASSWORD': 'password',
        'HOST': 'myserver.database.windows.net',
        'PORT': '',
        'OPTIONS': {
            'driver': 'ODBC Driver 18 for SQL Server',
        },
    },
}

# set this to False if you want to turn off pyodbc's connection pooling
DATABASE_CONNECTION_POOLING = False

Configuration Reference

Standard Django Settings

TEST Settings

OPTIONS

Backend-Specific Settings

Known Limitations

The following limitations apply when using SQL Server with Django:

• Altering a model field from or to AutoField at migration
• Floating point arithmetic in some annotate functions
• Annotate/exists function in order_by
• Righthand power and arithmetic with datetimes
• Timezones and timedeltas not fully supported
• Rename field/model with foreign key constraint
• Database level constraints and filtered indexes
• Date extract function
• Bulk insert with triggers and returning rows

Version-Specific Notes

JSONField lookups have additional limitations — see the JSONField wiki page.

Helpful Links

Still have questions?

Check the FAQ or open an issue on GitHub.

Contributing

We welcome contributions and suggestions! See CONTRIBUTING.md for details.

All contributors are listed on GitHub: Contributor Insights

Most contributions require a Contributor License Agreement (CLA). For details, visit https://cla.opensource.microsoft.com. A CLA bot will guide you when you submit a pull request.

This project has adopted the Microsoft Open Source Code of Conduct.

Security

For security reporting instructions please refer to SECURITY.md.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.