Resolução de problemas de instalação e ligação com mssql-python

Use este artigo para diagnosticar problemas de instalação, ligação, contentores e integração contínua (CI) com o mssql-python driver.

Problemas de instalação

o pip install falha ou compila a partir do código-fonte

Sintomas:

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

Possíveis causas e soluções:

  • Não há volante pré-montado para a tua plataforma

    • Verifica se corres uma versão Python suportada (3.10 e versões posteriores) e uma plataforma. Consulte ciclo de vida do suporte para a matriz de compatibilidade.
    • Atualize o pip antes da instalação com pip install --upgrade pip.
    • Para ambientes de equipa reproduzíveis, utilize o workflow bloqueado em Implementações reproduzíveis ou os padrões de contentores em Contentores e desenvolvimento local para reduzir a divergência das máquinas locais.

  • Ambiente virtual não ativado

    • Ative primeiro o seu ambiente virtual. A instalação do Python no sistema pode causar erros ou conflitos de permissões.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python

Instalações de drivers conflitantes

Sintomas:

Encontra erros de importação ou comportamentos inesperados depois de instalar mssql-python e pyodbc no mesmo ambiente.

Solution:

mssql-python e pyodbc podem coexistir. Se encontrares conflitos, cria um ambiente virtual limpo.

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

Problemas de conexão

Impossível ligar-se ao servidor

Sintomas:

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

Possíveis causas e soluções:

  • Servidor inacessível

    • Verifica se o nome do servidor e a porta estão corretos.
    • Verifique a conectividade de rede com ping <server> ou telnet <server> 1433.
    • Certifique-se de que o firewall permite ligações de saída na porta 1433.

  • SQL Server não está a correr

    • Verifique se o serviço SQL Server foi iniciado.
    • Para instâncias nomeadas, verifique se o serviço SQL Server Browser está a funcionar.

  • Regras de firewall do SQL do Azure

    • Adicione o endereço IP do seu cliente às regras do firewall SQL do Azure no portal Azure.
    • Para Azure SQL Managed Instance, certifique-se de que se liga a partir de uma rede permitida.

Teste a conectividade 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}")

Início de sessão falhado

Sintomas:

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

Possíveis causas e soluções:

  • Incompatibilidade dos modos de autenticação

    • Para Base de Dados SQL do Azure, Azure SQL Managed Instance e a base de dados SQL no Fabric, privilegie um modo do Microsoft Entra, como Authentication=ActiveDirectoryDefault.
    • Se usares autenticação SQL intencionalmente, verifica se o servidor o permite e que usas o formato de login correto para esse endpoint.

  • Credenciais de autenticação SQL incorretas

    • Verifique o ID de utilizador e a palavra-passe.
    • Para SQL do Azure, inclua o ID de utilizador completo: <user_id>@<server>.

  • O utilizador não existe na base de dados

    • Verifique se o utilizador tem acesso à base de dados especificada.
    • Verifique se o início de sessão está mapeado para um utilizador da base de dados.

  • Autenticação não configurada

    • Utilize a autenticação do Microsoft Entra (recomendada): Authentication=ActiveDirectoryDefault.
    • Se fizer uma resolução de problemas numa instância local do SQL Server que deva aceitar autenticação SQL, verifique se o SQL Server usa autenticação em modo misto.

Tempo limite de ligação

Sintomas:

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

Possíveis causas e soluções:

  • O servidor demora a responder

    • Aumente o tempo de espera da ligação.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Latência da rede

    • Verifique o caminho da rede até ao servidor.
    • Considere um caminho de rede mais curto ou uma rede privada virtual (VPN).

  • Servidor sob carga elevada

    • Tenta ligar durante as horas de menor afluência.
    • Contacte o administrador da sua base de dados.

Erros de certificado SSL

Sintomas:

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

Soluções:

Prefira um certificado de confiança ou os padrões de desenvolvimento local em Container e desenvolvimento local. Usa TrustServerCertificate=yes apenas para desenvolvimento local contra um servidor que controlas.

Para desenvolvimento e testes com um certificado auto-assinado:

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 é uma alternativa de recurso exclusivamente local. Não o leve para contentores de desenvolvimento partilhados, pipelines de CI ou implementações de produção. Para mais informações, consulte Encriptação e certificados.

Para produção, instale os certificados apropriados e utilize:

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

Questões de contentores e CI

Bibliotecas de sistema em falta no Linux

Sintomas:

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

Solution:

Instale os pacotes de sistema necessários para a sua distribuição:

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

Para exemplos de Dockerfile, veja Contentor e desenvolvimento local.

Erros SSL do macOS após a instalação

Sintomas:

O utilizador encontra erros relacionados com SSL ao ligar-se a partir de macOS, especialmente em Apple silicon.

Solution:

Instale o OpenSSL com Homebrew e defina as bandeiras do linker:

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

Conteúdo relacionado

  • Last updated on