Limitations and unsupported features in mssql-django

This article lists limitations of the mssql-django backend when used with SQL Server, Azure SQL Database, Azure SQL Managed Instance, and SQL database in Microsoft Fabric.

Django feature limitations

The following Django features aren't supported or have limited support with the mssql-django backend:

Migration limitations

JSONField limitations

• mssql-django maps JSONField to nvarchar(max). SQL Server 2025 introduced a native json type, but the Microsoft ODBC Driver for SQL Server doesn't expose it.
• The contains lookup isn't supported. Use key-path lookups instead (for example, filter(metadata__color="blue")).
• Quoted string values return with extra quotes (for example, '"value"' instead of 'value').
• Some nested lookups might behave differently than on PostgreSQL.
• For more information, see JSONField with SQL Server.

inspectdb limitations

• Composite primary keys aren't generated as unique_together automatically.
• Some SQL Server-specific column types might map to generic Django fields.
• Review and adjust generated models manually.
• For more information, see Reverse-engineer models with inspectdb.

SQL Server parameter limit

SQL Server limits each query to a maximum of 2,100 parameters. This limit affects Django operations that generate parameterized queries with large value lists:

Set batch_size on bulk operations and chunk large IN queries. See Performance tuning for solutions.

Bulk operations limitations

• bulk_create with return_rows_bulk_insert=False doesn't return IDs. Required for tables with triggers. See Bulk operations with mssql-django.

Test framework limitations

--keepdb is required when using managed identity authentication (ActiveDirectoryMsi) because the test runner can't create or destroy databases with that auth method.

For more information, see Test Django apps with SQL Server.

Version-specific notes

Django version-specific notes

Set up regex lookups

The mssql-django backend supports Django's __regex and __iregex lookups, but they require a one-time setup step. The backend ships a CLR assembly (regex_clr.dll) that provides a dbo.REGEXP_LIKE function to SQL Server.

Prerequisites

• A SQL Server instance that supports CLR integration. On-premises SQL Server and Azure SQL Managed Instance support CLR. Azure SQL Database doesn't support CLR assemblies, so __regex and __iregex lookups aren't available on Azure SQL Database.
• The connecting user must have sysadmin or ALTER SETTINGS permission. The management command enables CLR automatically.
• The mssql app must be in INSTALLED_APPS.

Install the CLR assembly

Run the management command, passing your database name:

python manage.py install_regex_clr <your-database-name>

This command performs the following steps:

1. Enables CLR on the server (sp_configure 'clr enabled', 1) if not already enabled.
2. Sets clr strict security to 0 (required for SAFE assemblies on SQL Server 2017+).
3. Creates the regex_clr assembly from the bundled DLL.
4. Creates the dbo.REGEXP_LIKE scalar function.

Use regex lookups

After installing the assembly, use __regex and __iregex in querysets:

# Case-sensitive regex
products = Product.objects.filter(name__regex=r"^Widget \d+$")

# Case-insensitive regex
products = Product.objects.filter(name__iregex=r"^widget \d+$")

The backend translates these lookups to dbo.REGEXP_LIKE(column, pattern, case_flag) = 1.

Related content

• Troubleshoot mssql-django
• FAQ
• mssql-django support and lifecycle
• GitHub issues