Referencia de configuración MSSQL-Django

Este artículo es la referencia completa settings.py de configuración para el backend de la mssql-django base de datos Django. Configura la conectividad de SQL Server editando el DATABASES diccionario en el archivo de settings.py tu proyecto Django.

Configuración mínima

El siguiente ejemplo muestra la configuración mínima requerida para la ruta predeterminada pyodbc :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Para ejecutar el alias mssql-python en su lugar, establece python_driver y omite driver. El mssql-python camino ignora driver:

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

ENGINE se "mssql" mantiene en ambos caminos. Los alias en el mismo proyecto pueden usar diferentes controladores. Para la lista completa de diferencias de comportamiento, véase Seleccionar el controlador de base de datos para mssql-django.

Salvo que se indique lo contrario, los ejemplos del resto de este artículo muestran el camino por defecto pyodbc .

Configuración de conexión a la base de datos

Estos ajustes configuran tu DATABASES conexión. La mayoría son configuraciones estándar de Django; Se señalan excepciones:

Setting	Tipo	Description
`ENGINE`	String	Debe ser `"mssql"`.
`NAME`	String	Nombre de la base de datos. Obligatorio.
`HOST`	String	Nombre de host del servidor o dirección IP. Usa `"server\\instance"` el formato para instancias con nombre.
`PORT`	String	Puerto de instancia de servidor. Cadena vacía significa puerto por defecto.
`USER`	String	Nombre del usuario de la base de datos. Si no se concede, se utiliza la Seguridad Integrada de Windows.
`PASSWORD`	String	Contraseña de usuario de la base de datos.
`AUTOCOMMIT`	Booleano	Configurado para `False` desactivar la gestión de transacciones de Django. El valor predeterminado es `True`.
`Trusted_Connection`	String	Configurado en `"yes"` (por defecto) para usar Seguridad Integrada de Windows cuando `USER` no se proporcione. Cuando `USER` y `PASSWORD` ambos se establecen, esas credenciales tienen prioridad y `Trusted_Connection` se ignoran. Configura para `"no"` desactivar explícitamente la autenticación de Windows. Esto es una `mssql-django` extensión, no un ajuste estándar de Django.
`TOKEN`	String	Token de acceso para la autenticación de Microsoft Entra (por ejemplo, mediante `azure.identity`). Esto es una `mssql-django` extensión, no un ajuste estándar de Django.

Configuración de TEST

Estos ajustes controlan la base de datos de pruebas utilizada por el ejecutor de pruebas de Django:

Setting	Tipo	Description
`NAME`	String	Nombre de la base de datos de pruebas. Valor predeterminado: `"test_" + NAME`.
`COLLATION`	String	Recopilación para la base de datos de pruebas. Por defecto: por defecto de instancia.
`DEPENDENCIES`	List	Dependencias del orden de creación de la base de datos.
`MIRROR`	String	Alias de una base de datos para espejar durante las pruebas.

Ejemplo:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
        "TEST": {
            "NAME": "test_mydb",
            "COLLATION": "SQL_Latin1_General_CP1_CI_AS",
        },
    },
}

OPCIONES

El OPTIONS diccionario proporciona una configuración específica del backend. Coloca estos ajustes dentro del DATABASES["default"]["OPTIONS"] diccionario:

Opción	Tipo	Predeterminado	Description
`python_driver`	String	Sin establecer	Configura para `"mssql_python"` conectar este alias a través del `mssql-python` controlador. No lo configura o `"pyodbc"` mantiene el driver por defecto `pyodbc` . Consulta Seleccionar el controlador de base de datos para mssql-django.
`driver`	String	`"ODBC Driver 18 for SQL Server"`	Controlador ODBC para usar. Automáticamente vuelve al controlador 17 si no está instalado el 18. Ignorado en el `mssql-python` camino.
`isolation_level`	String	`None`	Nivel de aislamiento de transacción: `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SNAPSHOT`o `SERIALIZABLE`.
`dsn`	String	`None`	Se llama DSN. Puede usarse en lugar de `HOST`. Ignorado en el `mssql-python` camino.
`host_is_server`	Booleano	`False`	Configura para `True` usarse `HOST`/`PORT` directamente con FreeTDS en lugar de un `freetds.conf` nombre de servidor de datos. Ignorado en el `mssql-python` camino.
`unicode_results`	Booleano	`False`	Activa la función de `unicode_results` pyodbc. Ignorado en el `mssql-python` camino.
`extra_params`	String	`None`	Parámetros adicionales de cadena de conexión en `"param=value;param=value"` formato. Usado para la autenticación Microsoft Entra. El `mssql-python` camino valida estos frente a una lista de permisos.
`collation`	String	`None`	Colocación para búsquedas de campos de texto (por ejemplo, `"Chinese_PRC_CI_AS"`).
`connection_timeout`	Integer	`0`	Tiempo de espera de conexión en segundos (`0` = desactivado). Usa al menos 60 para Azure SQL Database serverless con autopausa activada. Una base de datos en pausa automática se reanuda en el primer intento de conexión, y ese intento puede fallar con el error 40613 mientras la base de datos se reanuda, por lo que la aplicación debe intentarlo de nuevo. Para más información, consulta la pausa automática y la reanudación automática.
`connection_retries`	Integer	`5`	Número de intentos de reintento de conexión.
`connection_retry_backoff_time`	Integer	`5`	Tiempo de retirada en segundos entre intentos.
`query_timeout`	Integer	`0`	Tiempo de espera de consulta en segundos (`0` = desactivado).
`setencoding` / `setdecoding`	List	`None`	La configuración de codificación y decodificación pasaba a los métodos 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. `mssql-python` acepta `-99` para `SQL_WMETADATA`, y `pyodbc` lo rechaza. Consulta la referencia de codificación y decodificación pyodbc.
`return_rows_bulk_insert`	Booleano	`False`	Permite que las filas vuelvan desde la inserción a granel. Debe ser `False` si las tablas tienen desencadenantes.
`datefirst`	Integer	`7`	Primer día de la semana para `SET DATEFIRST`. `7`es domingo (por defecto de SQL Server), es `1` lunes.
`driver_needs_utf8`	Opción solo de presencia	Sin establecer	Activa la codificación UTF-8 para el controlador ODBC. Esta opción se activa cuando la clave está presente en `OPTIONS`; el valor en sí se ignora. Normalmente se necesita con FreeTDS o configuraciones antiguas de unixODBC que por defecto usan Latin-1.
`driver_charset`	String	`None`	Conjunto de caracteres explícito para el controlador ODBC (por ejemplo, `"UTF-8"`). Úsalo cuando `driver_needs_utf8` el controlador no detecta automáticamente la codificación.
`connection_recovery_interval_msec`	Flotante	`0.0`	Milisegundos para esperar entre intentos de reintento en el bucle de recuperación de conexión del backend tras un error de red. Aumenta este valor para enlaces de red inestables.

Ejemplo con opciones comunes:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes",
            "isolation_level": "READ COMMITTED",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 5,
            "query_timeout": 60,
        },
    },
}

Ajustes específicos del backend

Esta configuración se coloca a nivel de módulo en settings.py, fuera del DATABASES diccionario:

Setting	Tipo	Predeterminado	Description
`DATABASE_CONNECTION_POOLING`	Booleano	`True`	Configura para `False` desactivar la agrupación de conexiones a nivel de controlador. Se aplica tanto `pyodbc` a como `mssql-python`a .

Ejemplo:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

# Set this to False to disable driver-level connection pooling
DATABASE_CONNECTION_POOLING = False

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-09-29