Solucionar problemas de instalación y conexión con mssql-python

Utiliza este artículo para diagnosticar problemas de instalación, conexión, contenedor e integración continua (CI) con el mssql-python controlador.

Problemas de instalación

Fallos de instalación de pip o compilación desde el código fuente

Síntomas:

error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python

Posibles causas y soluciones:

• No hay volante preensamblado para tu plataforma

  • Comprueba que tienes una versión de Python compatible (versiones 3.10 y posteriores) y una plataforma. Consulta el ciclo de vida del soporte para la matriz de compatibilidad.
  • Actualiza pip antes de instalarlo con pip install --upgrade pip.
  • Para entornos de equipo reproducibles, utiliza el flujo de trabajo fijado en Repeatable deployments o los patrones de contenedores de Container and local development para reducir la desviación en las máquinas locales.

• Entorno virtual no activado

  • Activa primero tu entorno virtual. La instalación de Python en el sistema puede causar errores o conflictos de permisos.
  • Windows
  • Linux/macOS

  python -m venv .venv
  .venv\Scripts\activate
  pip install mssql-python
  

• Bibliotecas del sistema Linux que faltan
  • El controlador requiere varias librerías de sistema en Linux. Consulta Dependencias específicas de plataforma para los paquetes a instalar.

Instalaciones de controladores en conflicto

Síntomas:

Te encuentras con errores de importación o comportamientos inesperados después de instalar mssql-python y pyodbc en el mismo entorno.

Solution:

mssql-python y pyodbc pueden coexistir. Si te encuentras con conflictos, crea un entorno virtual limpio.

python -m venv .venv --clear
.venv\Scripts\activate
pip install mssql-python

python -m venv .venv --clear
source .venv/bin/activate
pip install mssql-python

Problemas de conexión

No se puede conectar al servidor

Síntomas:

OperationalError: [08001] (0) Client unable to establish connection

Posibles causas y soluciones:

• Servidor no accesible

  • Verifica que el nombre del servidor y el puerto sean correctos.
  • Comprueba la conectividad de red con ping <server> o telnet <server> 1433.
  • Asegúrate de que el cortafuegos permite conexiones salientes en el puerto 1433.

• SQL Server no está en ejecución

  • Verifica que el servicio SQL Server esté activado.
  • Para instancias nombradas, verifica que el servicio SQL Server Browser esté en funcionamiento.

• Reglas de firewall Azure SQL

  • Añade la dirección IP de tu cliente a las reglas del firewall de Azure SQL en el portal de Azure.
  • Para Azure SQL Managed Instance, asegúrate de conectarte desde una red permitida.

Prueba la conectividad TCP básica:

import socket

try:
    sock = socket.create_connection(("<server>.database.windows.net", 1433), timeout=5)
    print("TCP connection successful")
    sock.close()
except Exception as e:
    print(f"Cannot reach server: {e}")

Error de inicio de sesión

Síntomas:

OperationalError: [28000] (18456) Login failed for user '<user_id>'.

Posibles causas y soluciones:

• Incompatibilidad en el modo de autenticación

  • Para Azure SQL Database, Azure SQL Managed Instance y base de datos de SQL en Fabric, se prefiere un modo de Microsoft Entra como Authentication=ActiveDirectoryDefault.
  • Si usas autenticación SQL intencionadamente, verifica que el servidor lo permita y que uses el formato de inicio de sesión correcto para ese endpoint.

• Credenciales de autenticación SQL incorrectas

  • Verifica el ID de usuario y la contraseña.
  • Para Azure SQL, incluye el ID de usuario completo: <user_id>@<server>.

• El usuario no existe en la base de datos

  • Verifica que el usuario tenga acceso a la base de datos especificada.
  • Comprueba si el inicio de sesión está asignado a un usuario de la base de datos.

• Autenticación no configurada

  • Utiliza la autenticación de Microsoft Entra (recomendada): Authentication=ActiveDirectoryDefault.
  • Si solucionas un problema en una instancia local de SQL Server que debería aceptar autenticación SQL, verifica que SQL Server use autenticación en modo mixto.

Tiempo de espera de conexión

Síntomas:

OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired

Posibles causas y soluciones:

• El servidor tarda en responder

  • Aumenta el tiempo de espera de conexión.

  conn = mssql_python.connect(connection_string, timeout=60)
  

• Latencia de red

  • Comprueba la ruta de red hacia el servidor.
  • Considera una ruta de red más corta o una red privada virtual (VPN).

• Servidor bajo alta carga

  • Intenta conectarte en horas de menor tráfico.
  • Contacta con el administrador de tu base de datos.

Pago lento tras una interrupción de red

Si una connect() llamada se detiene al reutilizar una conexión del pool, actualiza el controlador y establece un tiempo de espera positivo para iniciar sesión:

conn = mssql_python.connect(connection_string, timeout=30)

Con el proveedor por defecto msodbcsql18, el controlador utiliza ese valor como un tiempo de espera temporal nativo para la operación de conexión durante la validación del pool, y luego intenta un inicio de sesión de reemplazo si la validación falla. Un explícito SQL_ATTR_LOGIN_TIMEOUT en attrs_before tiene prioridad. Si el tiempo de espera de inicio de sesión es cero o no especificado, el tiempo de espera temporal es de 15 segundos.

La validación puede implicar múltiples operaciones, la limpieza puede añadir tiempo y el inicio de sesión de reemplazo tiene su propio tiempo de espera. La adquisición de tokens Microsoft Entra ID no está limitada por el tiempo de espera de inicio de sesión. timeout=30 No es un plazo de 30 segundos para la validación ni para toda la llamada. Si el servidor o la red siguen sin estar disponibles, gestiona el error de conexión con la política de reintento de tu aplicación.

El proveedor de opt-in mssql-odbc no garantiza los mismos límites de validación. Para más información, consulte Comprobaciones de estado de conexión, limitaciones de proveedores nativos y lógica de reintentos.

Errores de certificado SSL

Síntomas:

OperationalError: [08001] SSL Provider: The certificate chain was issued by an authority that is not trusted

Soluciones:

Preferir un certificado de confianza o los patrones de desarrollo local en Contenedor y desarrollo local. Úsalo TrustServerCertificate=yes solo para desarrollo local contra un servidor que controlas.

Para desarrollo y pruebas con un certificado autofirmado:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # Don't use in production
)

Para producción, instala los certificados correspondientes y utiliza:

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

Problemas de contenedores y CI

Bibliotecas del sistema ausentes en Linux

Síntomas:

Cuando faltan libltdl o las bibliotecas de Kerberos, import mssql_python se ejecuta correctamente, pero la primera llamada a connect() genera OperationalError:

OperationalError: Driver Error: Connection operation failed; DDBC Error: Failed to load the driver. Please read the documentation (https://github.com/microsoft/mssql-python#installation) to install the required dependencies.

En Alpine Linux, cuando libstdc++ falta, import mssql_python falla:

ImportError: Error loading shared library libstdc++.so.6: No such file or directory

Solution:

Instala los paquetes de sistema necesarios para tu distribución:

Para ejemplos de Dockerfile, véase Contenedores y desarrollo local.

Errores SSL de macOS tras la instalación

Síntomas:

Te encuentras con errores relacionados con SSL cuando te conectas desde macOS, especialmente en Apple silicon.

Solution:

Instala OpenSSL con Homebrew y establece las banderas del enlazador:

brew install openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Contenido relacionado

• Instala el controlador mssql-python
• Cadenas de conexión para mssql-python
• Gestionar conexiones con mssql-python
• Cifrado y validación de certificados
• Contenedor y desarrollo local
• Solucionar problemas en mssql-python