Seleccione el controlador de base de datos para mssql-django

A partir de la versión 2.0, mssql-django se conecta a través de uno de dos controladores de bases de datos en Python:

• pyodbc con un controlador Microsoft ODBC instalado externamente para SQL Server. Este controlador es el predeterminado.
• mssql-python, el controlador Python de Microsoft, que no necesita un controlador ODBC instalado por separado.

Eliges el controlador para cada alias de base de datos. Un alias puede usar mssql-python, mientras que el resto del proyecto sigue en pyodbc. El ENGINE valor se mantiene "mssql" en ambos casos.

Optar por un alias en mssql-python

Establece la opción python_driver en el diccionario OPTIONS de ese alias:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "python_driver": "mssql_python",
            "extra_params": "Encrypt=yes",
        },
    },
}

El backend acepta "mssql_python", "mssql-python", y "python", y la comparación ignora el caso. Omite python_driver, déjalo vacío o ponlo en "pyodbc" modo que mantenga el controlador por defecto. Como la configuración es por alias, puedes revertir una base de datos a la vez eliminando la opción.

El mssql-python módulo se importa solo cuando un alias lo selecciona. Si la versión instalada es anterior a la 1.15.0, el backend sube ImproperlyConfigured con la versión requerida.

Requisitos de instalación

pip install mssql-django Instala ambos controladores. La mssql-python ruta no tiene una instalación separada de controladores ODBC. Una instalación de --no-deps, o un índice privado que no refleja mssql-python, hace que el paquete no se encuentre y que el alias falle en el momento de importar.

Instala los requisitos previos de la plataforma para mssql-python, incluyendo OpenSSL en macOS y las librerías necesarias en Linux.

Dado que mssql-python es una dependencia requerida, mssql-django 2.0 solo se instala en plataformas que cuentan con una distribución compatible de mssql-python. Para la lista de plataformas, véase soporte y ciclo de vida de mssql-django.

Diferencias de comportamiento

Los dos controladores construyen cadenas de conexión diferentes y exponen palabras clave de conexión distintas. Revisa esta sección antes de cambiar un alias.

Configuración de conexión

Los tiempos de espera, los reintentos, el nivel de aislamiento, la intercalación y return_rows_bulk_insert se comportan igual en ambas rutas.

Parámetros adicionales de conexión

mssql-python La versión 1.15 valida extra_params frente a una lista de permitidos y rechaza cualquier valor que no figure en ella. Las palabras clave admitidas incluyen Authentication, Encrypt, TrustServerCertificate, ServerCertificate, HostnameInCertificate, ServerSPN, MultiSubnetFailover, ApplicationIntent, ConnectRetryInterval, IpAddressPreference, ConnectRetryCount, KeepAlive, KeepAliveInterval y PacketSize.

El controlador rechaza MARS_Connection, APP, LongAsMax y ColumnEncryption, junto con palabras clave exclusivas de pyodbc, como WSID, AnsiNPW, UseFMTONLY, Description, Current Language, Connect Timeout, Network Library, Regional, QuotedId, SERVERNAME, DSN y DRIVER. Elimina esas palabras clave antes de cambiar un alias y usa la connection_timeout opción en lugar de Connect Timeout.

Cuando extra_params se establece una palabra clave que también genera el backend, gana el valor explícito.

Conjuntos de resultados activos múltiples (MARS)

En la ruta pyodbc, el backend añade MARS_Connection=yes cuando el alias usa un controlador ODBC de Microsoft en Windows. Se respeta un valor explícito MARS_Connection en extra_params en su lugar, y la coincidencia ignora el caso.

El mssql-python camino nunca activa MARS y rechaza la MARS_Connection palabra clave, así que no puedes activar MARS para ese alias.

Sin MARS, QuerySet.iterator() carga el resultado completo en memoria antes de devolver filas para que una consulta anidada pueda reutilizar la conexión, y chunk_size no cambia eso. Ten en cuenta el coste de memoria en conjuntos de consultas grandes.

Para endpoints que rechazan MARS, como Microsoft Fabric Warehouse, véase Desactivar MARS.

Configuración de codificación

Ambos controladores aceptan setencoding y setdecoding, y cada entrada se pasa al método de conexión del controlador seleccionado. Cada setdecoding entrada necesita una sqltype clave en ambos caminos, y la misma entrada funciona en cualquiera de los dos drivers. Una diferencia: mssql-python acepta -99 por SQL_WMETADATA, y pyodbc lo rechaza.

Elige entre los pilotos

Para desarrollos nuevos, use mssql-python. Elimina el paso de instalación del controlador ODBC en las imágenes de contenedor y en las implementaciones de App Service.

Úsalo pyodbc cuando tu despliegue depende de un DSN nombrado, FreeTDS, Always Encrypted mediante la ColumnEncryption palabra clave, una versión del controlador ODBC que gestiones tú mismo, o MARS. Para lo que MARS requiere en cada camino, véase Conjuntos de Resultados Activos Múltiples.

Los proyectos existentes pueden permanecer en pyodbc. Sigue siendo el predeterminado y está totalmente soportado. Cuando te muevas, cambia un alias a la vez y ejecuta tu suite de pruebas contra él antes de mover el resto.

Contenido relacionado

• Opciones de conexión para mssql-django
• Referencia de configuración de mssql-django
• Agrupación de conexiones en mssql-django
• autenticación de Microsoft Entra con mssql-django
• controlador mssql-python para SQL Server