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.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python

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

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 SQL Database en Fabric, se prefiere un modo de autenticación 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.

Errores de certificado SSL

Síntomas:

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

Soluciones:

Prefiera 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
)

Caution

TrustServerCertificate=yes es un recurso de respaldo solo local. No lo introduzcas en contenedores de desarrollo compartidos, canalizaciones de CI ni despliegues en producción. Para más información, véase Cifrado y certificados.

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:

ImportError: libltdl.so.7: cannot open shared object file: No such file or directory
ImportError: libkrb5.so.3: cannot open shared object file

Solution:

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

Distribution Comando Install
Ubuntu o Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat o Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

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

  • Last updated on