Limitaciones y funciones no soportadas en mssql-django

Este artículo enumera las limitaciones del mssql-django backend cuando se utiliza con SQL Server, Azure SQL Database, Azure SQL Managed Instance y la base de datos SQL en Microsoft Fabric.

Limitaciones de las funciones de Django

Las siguientes funciones de Django no son compatibles o tienen soporte limitado en el mssql-django backend:

Feature Situación Details
Avg con DurationField No soportado El agregado Avg no funciona en DurationField.
__regex y __iregex búsquedas Requiere instalación Compatible tras instalar el ensamblador CLR en SQL Server o Azure SQL Managed Instance. Azure SQL Database no soporta ensambladores CLR. Consulta Configurar consultas de regex.
DISTINCT ON No soportado SQL Server no soporta DISTINCT ON cláusulas. Uso .values().distinct() o subconsultas.
Subquery en ORDER BY No soportado Ordenar por expresiones de subconsulta puede no funcionar.
Nivel de base de datos CASCADE Limitado Algunas SET NULLSET DEFAULT operaciones y pueden requerir migración manual de SQL.
DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT No soportado Acciones referenciales a nivel de base de datos añadidas en Django 6.1. SQL Server rechaza grafos de clave foránea con múltiples rutas en cascada hacia la misma tabla (error 1785), por lo que no hay una ruta nativa para esta función en ninguna versión de SQL Server. Usar uno de estos valores eleva la comprobación fields.E324del sistema Django . Usa el nivel on_delete estándar de Django en su lugar.
BitAnd, BitOr, BitXor No soportado Agregados bit a bit añadidos en Django 6.1. SQL Server no tiene una función nativa de agregado bit a bit, y el backend no los emula, por lo que estos agregados generan NotSupportedError.
is_dst en Trunc/Extract No soportado is_dst (usado para resolver horarios ambiguos durante las transiciones del horario de verano) en Extract() y Trunc() no es compatible. Úsalo AT TIME ZONE en SQL en bruto para consultas conscientes del horario de verano.
Anotación en coma flotante Limitado Los agregados de coma Avg flotante pueden perder precisión en comparación con PostgreSQL debido al comportamiento de tipo float de SQL Server. Por ejemplo, promediar 0,1 y 0,2 podría dar 0,1500000000000000002222 en lugar de exactamente 0,15. Úsalos DecimalField o Cast(avg_expr, output_field=DecimalField()) para cálculos financieros críticos.
Anotar/existes en ORDER BY No soportado Usar anotar o expresiones existentes puede order_by no funcionar.
Potencia de la mano derecha y aritmética de fecha No soportado Las operaciones de potencia a la derecha (por ejemplo, F('value') ** 2 funcionan pero 2 ** F('value') fallan) y la división con timedelta no están soportadas.
Huso horarios y diferencias horarias Limitado Las zonas horarias y los deltas temporales no están totalmente soportados. Consulta el soporte de huso horario en mssql-django.
QuerySet.iterator() sin MARS Limitado La ruta mssql-python no habilita Múltiples Conjuntos de Resultados Activos (MARS). En la ruta pyodbc, MARS está habilitado por defecto con un controlador Microsoft ODBC en Windows, y MARS_Connectionextra_params se respeta sin distinción a mayúsculas y minúsculas. Cuando MARS está apagado, QuerySet.iterator() almacena todo el resultado en memoria antes de ceder. chunk_size no cambia este comportamiento.
NthValue Función ventana No soportado SQL Server no soporta NTH_VALUE(). Usa FIRST_VALUE, LAST_VALUE, o una subconsulta.
ignore_conflicts en bulk_create No soportado bulk_create(objs, ignore_conflicts=True) no es compatible. SQL Server no tiene equivalente a PostgreSQL ON CONFLICT DO NOTHING.
Búsqueda JSONField contains No soportado Utiliza búsquedas por trayectorias de clave (por ejemplo, filter(metadata__color="blue")). Véase limitaciones de JSONField.
select_for_update(of=(...)) No soportado SQL Server no soporta bloquear tablas específicas. El backend eleva NotSupportedError. Consulta Gestión de transacciones.

Limitaciones de la migración

Limitación Details
Alter AutoField No se puede cambiar un campo a o desde AutoField (IDENTITY columna). Requiere crear una nueva tabla.
Renombrar con llaves extranjeras Renombrar una columna que tiene restricciones de clave externa puede fallar. Utilice SeparateDatabaseAndState.
AddConstraint / RemoveConstraint Conflictos Algunas operaciones de restricción pueden entrar en conflicto. Solicita en migraciones separadas.
Operaciones de extracción de fechas ExtractYear, ExtractMonth, y operaciones similares tienen un soporte limitado tzinfo .

Limitaciones de JSONField

  • mssql-djangoMapas JSONField a Nvarchar(Max). SQL Server 2025 introdujo un tipo nativo de json, pero el controlador ODBC de Microsoft para SQL Server no lo expone.
  • La contains consulta no está soportada. Utiliza búsquedas por trayectorias de clave (por ejemplo, filter(metadata__color="blue")).
  • Los valores de cadenas comillas se devolven con comillas adicionales (por ejemplo, '"value"' en lugar de 'value').
  • Algunas búsquedas anidadas pueden comportarse de forma diferente a las de PostgreSQL.
  • Para más información, consulta JSONField con SQL Server.

Limitaciones de InspectDB

  • Las claves primarias compuestas no se generan automáticamente unique_together .
  • Algunos tipos de columnas específicos de SQL Server pueden asignarse a campos genéricos de Django.
  • Revisa y ajusta manualmente los modelos generados.
  • Para más información, véase Ingeniería inversa de modelos con inspectdb.

Límite de parámetros de SQL Server

SQL Server limita cada consulta a un máximo de 2.100 parámetros. Este límite afecta a las operaciones de Django que generan consultas parametrizadas con listas de valores grandes:

Operación Cómo llega al límite
filter(field__in=large_list) Cada elemento de la lista se convierte en un parámetro. El backend optimiza automáticamente más de 2.048 elementos en una tabla temporal.
prefetch_related() Cada ID de objeto padre se convierte en un parámetro en la cláusula de WHERE IN la consulta relacionada. Auto-optimizado como filter(field__in=...) cuando supera los 2.048 IDs.
bulk_create() Cada campo de cada objeto se convierte en un parámetro. Un modelo con 10 campos y 250 objetos genera 2.500 parámetros.
bulk_update() Cada campo utiliza dos parámetros por objeto (uno para la coincidencia PK y otro para el valor).
Q() con muchas condiciones Cada valor en objetos encadenados Q se convierte en un parámetro.

Haz batch_size operaciones masivas y haz consultas grandes IN por bloques. Consulta ajuste de rendimiento para soluciones.

Limitaciones de operaciones a granel

Limitaciones del marco de pruebas

--keepdb es necesario cuando se utiliza autenticación de identidad gestionada (ActiveDirectoryMsi) porque el ejecutor de pruebas no puede crear ni destruir bases de datos con ese método de autenticación.

Para más información, consulta Probar aplicaciones Django con SQL Server.

Notas específicas de la versión

Versión MSSQL-Django Notas
2.0 Soporta Python 3.10 a 3.14, Django 5.2, 6.0 y 6.1, SQL Server 2017, 2019, 2022 y 2025, Azure SQL Database, Azure SQL Managed Instance y SQL Database en Microsoft Fabric. Añade la ruta del controlador mssql-python manteniendo pyodbc como predeterminado. Para más información, consulte Seleccionar el controlador de base de datos para mssql-django.
1.8.0 Utiliza esta versión para proyectos que requieran Python 3.8, Python 3.9 o una versión de Django anterior a la 5.2.

Las combinaciones probadas de mssql-django 2.0 son Django 5.2 con Python 3.10 a 3.13, y Django 6.0 o 6.1 con Python 3.12 a 3.14. Si el backend se conecta a una versión mayor más reciente de SQL Server no reconocida, utiliza el último conjunto de capacidades que conoce en lugar de fallar la validación de versión. Este comportamiento no declara que las funciones no probadas estén soportadas.

Notas específicas de la versión de Django

Versión de Django Notas
5.2 CompositePrimaryKey El apoyo es parcial. inspectdb Todavía requiere correcciones manuales, la comparación de tuplas con subconsultas requiere Django 5.2.4 y versiones posteriores, y algunas migraciones más las rutas de actualización masiva/CASE WHEN de JSONField siguen teniendo exclusiones en las pruebas. Para más información, consulta el repositorio de GitHub.
6.0 Requiere Python 3.12 y versiones posteriores. Se aplican todas las limitaciones de la 5.2. El backend gestiona todos los cambios de la API 6.0 de forma transparente.
6.1 Requiere Python 3.12 y versiones posteriores. Se aplican todas las limitaciones de la 6.0. Requiere mssql-django versiones 1.8.0 y posteriores. No se soportan acciones referenciales a nivel de base de datos (DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT) y agregados bit a bit (BitAnd, BitOr, BitXor)

Configurar búsquedas de regex

El mssql-django backend soporta Django __regex y __iregex consultas, pero requieren un paso de configuración único. El backend incluye un ensamblador CLR (regex_clr.dll) que proporciona una dbo.REGEXP_LIKE función a SQL Server.

Prerequisites

  • Una instancia de SQL Server que soporta integración CLR. On-premises SQL Server y Azure SQL Managed Instance soportan CLR. Azure SQL Database no soporta ensambladores CLR, así que __regex__iregex las consultas no están disponibles en Azure SQL Database.
  • El usuario que se conecta debe tener sysadmin un permiso ALTER SETTINGS . El comando de gestión activa automáticamente el CLR.
  • La mssql aplicación debe estar en INSTALLED_APPS.

Instala el conjunto CLR

Ejecuta el comando de gestión, pasando el nombre de tu base de datos:

python manage.py install_regex_clr <database>

Este comando realiza los siguientes pasos:

  1. Activa CLR en el servidor (sp_configure 'clr enabled', 1) si no está ya activado.
  2. Se establece clr strict security en 0 (necesario para SAFE ensambladores en SQL Server 2017 y versiones posteriores).
  3. Crea el regex_clr ensamblador a partir de la DLL agrupada.
  4. Crea la dbo.REGEXP_LIKE función escalar.

Caution

Configurar clr strict security para 0 permite que se carguen ensamblajes CLR sin signo. Esto es necesario porque el paquete regex_clr.dll no está firmado. Comenta este cambio con tu DBA antes de ejecutar el comando en servidores de producción. La configuración se aplica a todo el servidor, no a cada base de datos.

Utiliza consultas regulares

Después de instalar el ensamblaje, usa __regex y __iregex en los conjuntos de consultas:

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

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

El backend traduce estas búsquedas a dbo.REGEXP_LIKE(column, pattern, case_flag) = 1.

Importante

dbo.REGEXP_LIKE ignora el espacio en blanco literal en el patrón. Un patrón como ^Widget \d+$ se compara con si fuera ^Widget\d+$, por lo que no devuelve filas contra el valor Widget 42. Escribe espacios como \s o como una clase de carácter como [ ]. No surge nada, así que el resultado vacío parece un problema de datos.

Nota:

Debes ejecutar el install_regex_clr comando una vez por base de datos. Si la base de datos se descarta y se recrea (por ejemplo, durante las pruebas), ejecuta el comando de nuevo.

Contenido relacionado

  • Last updated on