Solucionar problemas de instalação e conexão com mssql-python

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

Problemas de instalação

o pip falha ao instalar 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:

  • Sem volante pré-montado para sua plataforma

    • Verifique se você usa uma versão de Python suportada (versões 3.10 e posteriores) e uma plataforma. Veja ciclo de vida de suporte para a matriz de compatibilidade.
    • Atualize o pip antes da instalação com pip install --upgrade pip.
    • Para ambientes reproduzíveis para a equipe, use o fluxo de trabalho bloqueado em Implantações reproduzíveis ou os padrões de contêiner em Contêineres e desenvolvimento local para reduzir a divergência entre máquinas locais.

  • Ambiente virtual não ativado

    • Ative seu ambiente virtual primeiro. 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 conflitantes de drivers

Sintomas:

Você encontra erros de importação ou comportamentos inesperados após instalar mssql-python e pyodbc no mesmo ambiente.

Solution:

mssql-python e pyodbc podem coexistir. Se você encontrar conflitos, crie um ambiente virtual limpo.

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

Problemas de conexão

Não consigo conectar ao servidor

Sintomas:

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

Possíveis causas e soluções:

  • Servidor não acessível

    • Verifique 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 permita conexões de saída na porta 1433.

  • SQL Server não está rodando

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

  • Regras de firewall do SQL do Azure

    • Adicione seu endereço IP do cliente às regras do firewall SQL do Azure no portal Azure.
    • Para Instância Gerenciada de SQL do Azure, certifique-se de se conectar 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}")

Falha no logon

Sintomas:

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

Possíveis causas e soluções:

  • Incompatibilidade no modo de autenticação

    • Para o Banco de Dados SQL do Azure, a Instância Gerenciada de SQL do Azure e o banco de dados SQL no Fabric, dê preferência a um modo do Microsoft Entra, como Authentication=ActiveDirectoryDefault.
    • Se você usar autenticação SQL intencionalmente, verifique se o servidor permite e se você usa o formato de login correto para aquele endpoint.

  • Credenciais de autenticação SQL incorretas

    • Verifique o ID do usuário e a senha.
    • Para SQL do Azure, inclua o ID de usuário completo: <user_id>@<server>.

  • O usuário não existe no banco de dados

    • Verifique se o usuário tem acesso ao banco de dados especificado.
    • Verifique se o login está mapeado para um usuário do banco de dados.

  • Autenticação não configurada

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

Tempo de espera da conexão esgotado

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 limite da conexão.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Latência da rede

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

  • Servidor sob carga pesada

    • Tente se conectar durante os horários fora do pico.
    • Entre em contato com o administrador do seu banco 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 confiável ou as práticas de desenvolvimento local em Container and local development. Use TrustServerCertificate=yes apenas para desenvolvimento local em um servidor que você controla.

Para desenvolvimento e testes com um certificado autoassinado:

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 fallback apenas local. Não carregue isso em contêineres de desenvolvimento compartilhados, pipelines de CI ou implantações em produção. Para mais informações, veja Criptografia 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 contêiner e CI

Bibliotecas de sistema ausentes 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 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 Container e desenvolvimento local.

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

Sintomas:

Você encontra erros relacionados ao SSL ao conectar pelo macOS, especialmente no Apple Silicon.

Solution:

Instale o OpenSSL com o Homebrew e defina as opções do vinculador:

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