Cadenas de conexión para mssql-python

El controlador mssql-python soporta las siguientes palabras clave de cadena de conexión al conectarse a SQL Server, Azure SQL Database, Azure SQL Managed Instance y base de datos SQL en Microsoft Fabric.

Sintaxis de cadenas de conexión

Las cadenas de conexión utilizan pares clave-valor separados por punto y coma:

keyword1=value1;keyword2=value2;...

Valores de envolvente que contienen caracteres especiales (puntos y coma, signos iguales o clavijas curvadas) entre clavijas curvadas:

PWD={my;complex=password}

Para incluir un soporte literal de cierre en un valor, utiliza dos clavijas de cierre (}}):

PWD={password}}with}}brace}

Ejemplos básicos de conexión

Los siguientes ejemplos muestran cómo conectarse usando diferentes métodos de autenticación. Para aplicaciones de producción, utiliza la autenticación Microsoft Entra siempre que sea posible. Elimina las contraseñas de tu código y de las cadenas de conexión.

SQL Server con autenticación Microsoft Entra (recomendado)

Este ejemplo utiliza ActiveDirectoryDefault, que prueba múltiples fuentes de credenciales (CLI de Azure, variables de entorno, identidad gestionada) en orden. No se almacena ninguna contraseña en el código:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Authentication=ActiveDirectoryDefault;Encrypt=yes;"
)

SQL Server con autenticación SQL

Usa autenticación SQL solo para desarrollo local en una instancia de SQL Server que controles. Las credenciales están incrustadas en la cadena de conexión, así que mantenlas en variables de entorno o en un .env archivo en lugar de en código fuente:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL con autenticación Microsoft Entra

La cadena de conexión para Azure SQL Database es la misma que para SQL Server. ActiveDirectoryDefaultfunciona en entornos de desarrollo local, contenedores y alojados en Azure sin cambios en el código:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Usar argumentos por palabras clave

Puedes pasar parámetros de conexión como argumentos de palabra clave en lugar de o además de una cadena de conexión. Los argumentos de palabras clave evitan los errores escapatorios del ensamblaje de cadena de conexión. Las contraseñas con caracteres especiales como @, ;, {, o } que no necesitan envolvimiento con llaves rizados cuando se pasan como argumentos de palabra clave:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Compárese con cadena de conexión assembly, donde debe envolverse una contraseña que contenga @ a:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

El controlador fusiona los argumentos de palabras clave en la cadena de conexión tras la normalización. Si un argumento de palabra clave coincide con un parámetro ya presente en la cadena de conexión, el argumento de palabra clave tiene prioridad y anula el valor de la cadena de conexión:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

El siguiente ejemplo combina una cadena de conexión con argumentos de palabras clave:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Palabras clave de cadena de conexión

Servidor y base de datos

Especifica la instancia y base de datos de SQL Server objetivo para la conexión.

Autenticación

Proporciona credenciales para la autenticación SQL o especifica un modo de autenticación Microsoft Entra. Para opciones sin contraseña, véase modos de autenticación Microsoft Entra.

Cifrado y seguridad

Todas las conexiones se usan Encrypt=yes por defecto. Para la mayoría de las aplicaciones, el valor por defecto es suficiente. Úsalo strict solo cuando tu instancia de SQL Server soporte TDS 8.0 y necesites TLS 1.3. Úsalo TrustServerCertificate=yes solo en entornos de desarrollo con certificados autofirmados.

Alta disponibilidad y conmutación por error

Estas palabras clave se aplican a los despliegues de grupos de disponibilidad Always On. Configura ApplicationIntent=ReadOnly para enrutar cargas de trabajo con mucha lectura (informes, analítica) a réplicas secundarias, reduciendo la carga en el principal. Establece MultiSubnetFailover=yes cuándo tu grupo de disponibilidad abarca varias subredes.

Rendimiento y red

Los valores por defecto funcionan para la mayoría de las aplicaciones. Aumenta PacketSize (hasta 32767) para transferencias masivas de datos. Configura KeepAlive si las conexiones cruzan cortafuegos o balanceadores de carga que abandonan las sesiones TCP inactivas.

Palabras clave reservadas

Modos de autenticación de Microsoft Entra

La Authentication palabra clave soporta los siguientes valores. Elige el modo que se adapte a tu despliegue:

Para la configuración reproducible de Docker, devcontainer y entorno CI, véase Contenedores y desarrollo local. Ese artículo centraliza la selección de tiempo de ejecución en Python y muestra cómo usar imágenes fijadas en resumen en entornos compartidos.

Ejemplo: DefaultAzureCredential

ActiveDirectoryDefaultse asigna a la cadena de identidad DefaultAzureCredential de Azure. Prueba primero el token CLI de Azure durante el desarrollo local, y luego la identidad gestionada cuando se despliega en Azure:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Ejemplo: Flujo de código de dispositivo

Utiliza el flujo de código del dispositivo cuando se ejecuta en entornos sin navegador, como sesiones SSH o contenedores Docker. El controlador muestra una URL y un código para introducir en un dispositivo separado:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Ejemplo: Principal de servicio

La autenticación del principal de servicio utiliza una identidad de aplicación registrada con un ID de cliente y un secreto. Utiliza este enfoque para canalizaciones CI/CD y servicios en segundo plano que se ejecutan sin interacción del usuario:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

Para registrar la aplicación y concederle acceso a la base de datos, consulte Microsoft Entra service principals with Azure SQL. Para la configuración completa en mssql-python, véase autenticación del principal de servicio.

Tiempo de espera de conexión

Establece el tiempo de espera de la conexión usando el timeout parámetro. Utiliza un tiempo de espera para evitar que tu aplicación se quede colgada indefinidamente cuando el servidor no sea accesible:

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

También puedes cambiar el tiempo de espera en una conexión existente:

conn.timeout = 60

Modo de confirmación automática

Por defecto, autocommit es False, lo que requiere llamadas explícitas commit() . Activa el autocommit para sentencias DDL o consultas de solo lectura que no necesiten control de transacciones:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Atributos de conexión

Establezca los atributos de la conexión ODBC antes de que se establezca la conexión usando attrs_before:

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Construcción programática de cadena de conexión

Para evitar la inyección de cadena de conexión, no uses concatenación de cadenas ni cadenas f con entrada del usuario. Utiliza argumentos de palabras clave o variables de entorno en su lugar. Para más patrones de construcción incluyendo archivos de configuración JSON/YAML, Azure Key Vault y una clase builder, consulta Build connection strings programáticamente.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Validación de cadenas de conexión

El controlador valida cadenas de conexión y aumenta ConnectionStringParseError las señales para palabras clave desconocidas o mal escritas:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Contenido relacionado

• Construir cadenas de conexión de forma programática
• Instalar mssql-python
• Autenticación de Microsoft Entra
• Agrupación de conexiones
• Administración de conexiones