Opciones de conexión para mssql-django

Este artículo explica la configuración del diccionario OPTIONS en tu configuración de Django DATABASES. Esta configuración controla cómo mssql-django se conecta a SQL Server a través del controlador ODBC.

Selección de controladores ODBC

A partir de la versión mssql-django 1.7, el backend usa de forma predeterminada ODBC Driver 18 para SQL Server. Si odbc Driver 18 no está instalado, el back-end vuelve automáticamente al controlador ODBC 17.

Puede especificar explícitamente el controlador:

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

En Linux, también puede especificar la ruta de acceso completa a la biblioteca de controladores:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.0.so.1.1",
        },
    },
}

DSN frente a HOST

Puedes conectarte utilizando un nombre HOST o un DSN (nombre de origen de datos) con nombre.

Conexión con HOST

La mayoría de las configuraciones usan directamente el ajuste HOST:

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",
        },
    },
}

Conexión con DSN

Use un DSN con nombre configurado en los orígenes de datos ODBC:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "OPTIONS": {
            "dsn": "MyDataSourceName",
        },
    },
}

Compatibilidad con FreeTDS

Para usar FreeTDS como controlador ODBC, establezca host_is_server en True. Esto indica al back-end que use HOST y PORT directamente en lugar de buscar un nombre de servidor de datos en freetds.conf:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "FreeTDS",
            "host_is_server": True,
        },
    },
}

Para obtener más información sobre las conexiones sin DSN con FreeTDS, consulte la guía del usuario de FreeTDS.

Parámetros ODBC adicionales

Use extra_params para pasar parámetros adicionales de la cadena de conexión ODBC. El valor es una cadena delimitada por punto y coma anexada al cadena de conexión:

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": "TrustServerCertificate=yes;ApplicationIntent=ReadOnly",
        },
    },
}

Esta configuración también se utiliza para las palabras clave de autenticación de Microsoft Entra.

Al conectarse a Azure SQL Database, Azure SQL Managed Instance, una base de datos SQL en Microsoft Fabric, un agente de escucha de un grupo de disponibilidad o una instancia de clúster de conmutación por error, agregue MultiSubnetFailover=Yes a extra_params. Cuando el nombre del servidor se resuelve en más de una dirección IP, el controlador se conecta a todas esas direcciones al mismo tiempo y utiliza la primera que responde primero. Sin ella, el controlador prueba las direcciones una a una, y una dirección que no responde consume el tiempo de autenticación restante antes de pasar a la siguiente. Cuando DNS se resuelve en una única dirección, el controlador realiza un único intento de conexión, por lo que se puede dejar esta opción activada con seguridad.

MultiSubnetFailover=Yes tiene los siguientes límites:

• No puedes usarlo sobre un protocolo que no sea TCP.

• Falla la conexión a una instancia de SQL Server configurada con más de 64 direcciones IP.

• No puedes usarlo con el espejado de bases de datos. El controlador devuelve un error cuando la cadena de conexión especifica Failover_Partner, y también cuando el servidor informa de que la base de datos está reflejada. El reflejo de bases de datos está obsoleto en todas las versiones compatibles de SQL Server. Use en su lugar los grupos de disponibilidad de Always On.

Tiempos de espera y reintentos de conexión

Configure la resiliencia de la conexión con la configuración de tiempo de espera y reintento:

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",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "query_timeout": 120,
        },
    },
}

connection_timeout=0 es el MSSQL-Django por defecto. Como pyodbc solo llama SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, ...) cuando se proporciona un valor positivo, se aplica el valor por defecto dependiente del controlador (15 segundos para el controlador ODBC de Microsoft para SQL Server). Establece un valor explícito para que los intentos de conexión no responsivos fallen predeciblemente.

Si el objetivo es Azure SQL Database serverless con autopausa activada, usa al menos 60. 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. Con un tiempo de espera más corto, el primer intento de conexión expira antes de que se complete la reanudación. connection_retries Finalmente tiene éxito, pero la primera petición espera varios tiempos de espera antes de conectarse. Para más información, consulta la pausa automática y la reanudación automática.

Collation

Establezca una intercalación personalizada para las búsquedas de campos de texto:

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",
            "collation": "Chinese_PRC_CI_AS",
        },
    },
}

Varias conexiones de base de datos

Django admite la conexión a varias bases de datos simultáneamente. Esto resulta útil para las réplicas de lectura, las consultas entre bases de datos o la separación de cargas de trabajo por nivel de aislamiento.

Configuración de varias bases de datos

Defina cada conexión en la opción DATABASES.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-primary-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
    "readonly": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-readonly-replica>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes;ApplicationIntent=ReadOnly",
        },
    },
    "analytics": {
        "ENGINE": "mssql",
        "NAME": "analytics_db",
        "HOST": "<your-analytics-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "isolation_level": "READ UNCOMMITTED",
        },
    },
}

Enruta las consultas con un enrutador de base de datos

Cree un enrutador de base de datos para dirigir las operaciones de lectura y escritura a la conexión adecuada:

class ReadReplicaRouter:
    """Route read queries to the readonly replica, writes to the primary."""

    def db_for_read(self, model, **hints):
        return "readonly"

    def db_for_write(self, model, **hints):
        return "default"

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return db == "default"

Registre el router en settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Guarde la clase de enrutador en un archivo como myproject/routers.py.

Consulta directa de una base de datos específica

Use el using() método para consultar un alias de base de datos específico:

# Explicit read from analytics database
reports = AnalyticsReport.objects.using("analytics").filter(date__gte="2025-01-01")

# Write to default
Product.objects.create(name="Widget", price=9.99)

Para obtener más información sobre los niveles de aislamiento en las bases de datos por conexión, consulte Lectura de datos sin bloqueo.

Contenido relacionado

• Referencia de configuración de mssql-django
• autenticación de Microsoft Entra con mssql-django
• Lógica de reintento y resiliencia de la conexión con mssql-django
• Procedimientos recomendados de seguridad para mssql-django
• Agrupación de conexiones en mssql-django
• Solución de problemas de mssql-django