Solucionar problemas no mssql-python

Use este artigo para encontrar orientações de solução de problemas para o mssql-python motorista. Comece pelo sintoma ou mensagem de erro que corresponde ao seu problema.

Problemas de instalação

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

Para versões de Python não suportadas, rodas ausentes, ambientes virtuais inativos e bibliotecas Linux ausentes, veja Solucionar problemas de instalação e conexão.

Instalações conflitantes de drivers

Para erros de importação ou comportamentos inesperados quando mssql-python e pyodbc são instalados juntos, veja Solucionar problemas de instalação e conexão.

Problemas de conexão

Não consigo conectar ao servidor

Para SQLSTATE08001, servidores inalcançáveis, serviços parados e regras de firewall SQL do Azure, veja Solucionar problemas de instalação e conexão.

Falha no logon

Para SQLSTATE 28000, incompatibilidades de modo de autenticação, credenciais inválidas e usuários de banco de dados ausentes, veja Solucionar problemas de instalação e conexão.

Tempo de espera da conexão esgotado

Para SQLSTATE HYT00 ou HYT01, latência de rede, servidores lentos e configurações de tempo de conexão (timeout), veja Solucionar problemas de instalação e conexão.

Erros de certificado SSL

Para erros de certificado não confiáveis e opções seguras de desenvolvimento local, veja Solucionar problemas de instalação e conexão.

Problemas de execução de consultas

Tabela ou objeto não encontrado

Para SQLSTATE 42S02, contexto do banco de dados, qualificação de esquema e verificações da existência de tabelas, consulte Solucionar problemas de consulta, dados e operação.

Erro de sintaxe

Para SQLSTATE 42000, sintaxe SQL, escape de cadeia de caracteres e consultas parametrizadas, consulte Solucionar problemas de consulta, dados e operação.

Erros de parâmetros

Para SQLSTATE 07001, quantidade de placeholders e estilos de parâmetros compatíveis, consulte Solucionar problemas de consulta, dados e operação.

Questões com tipos de dados

Erros de conversão de data e hora

Para obter informações sobre SQLSTATE 22007 e a conversão do parâmetro datetime, consulte Solucionar problemas de consulta, dados e operação.

Questões de precisão decimal

Para valores decimais truncados ou arredondados, veja Solucionar problemas de consulta, dados e operações.

Problemas de codificação Unicode

Para caracteres especiais distorcidos e tipos de coluna Unicode, consulte Solucionar problemas de consulta, dados e operação.

Problemas de desempenho

Execução lenta da consulta

Para indexação, grandes conjuntos de resultados e pooling de conexões, veja Solucionar problemas de consulta, dados e operações.

Problemas de memória com resultados grandes

Para streaming e paginação de grandes conjuntos de resultados, veja Solucionar problemas de consulta, dados e operações.

Questões de transação

Escopo de tabelas temporárias com autocommit

Para tabelas temporárias que desaparecem após rollback e instruções DDL que exigem autocommit, consulte Solução de problemas de consulta, dados e operação.

Transação não comprometida

Para alterações de dados que não persistem após o fechamento da conexão, veja Solucionar problemas de consulta, dados e operação.

Erros de deadlock

Para obter orientações sobre SQLSTATE 40001, nova tentativa e análise de deadlocks recorrentes, consulte Solucionar problemas de consulta, dados e operação.

Problemas de carregamento em massa

Violações de restrições durante a cópia em massa

Para violações de chave primária, única, verificação ou chave estrangeira durante cópias em massa, veja Solucionar problemas de consulta, dados e operação.

Erros de mapeamento de colunas

Para incompatibilidades na contagem e na ordem das colunas em cópia em massa, consulte Solucionar problemas de consulta, dados e operação.

Incompatibilidades de tipo durante a cópia em massa

Para valores truncados, arredondados ou incorretos após cópia em massa, consulte Solucionar problemas de consulta, dados e operação.

Falhas na vinculação de tipos do NumPy

Para falhas na vinculação de parâmetros com tipos inteiros ou de ponto flutuante do NumPy, veja Solucionar problemas de consulta, dados e operação.

Cópia em massa com tabelas temporárias

Para erros Invalid object name ao usar bulkcopy() com uma tabela temporária de sessão, consulte Solucionar problemas de consulta, dados e operação.

Questões de contêiner e CI

Bibliotecas de sistema ausentes no Linux

Para a ausência das bibliotecas libltdl ou Kerberos em ambientes Linux, consulte Resolver problemas de instalação e conexão.

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

Para erros relacionados a SSL no macOS, incluindo o Apple Silicon, veja Solucionar problemas de instalação e conexão.

Ferramentas de diagnóstico

Ativar o log do driver

Use mssql_python.setup_logging() para ativar o registro em DEBUG. O driver registra instruções SQL, parâmetros, operações ODBC internas e mudanças de estado da conexão.

import mssql_python

# Enable logging to file (default)
mssql_python.setup_logging()

# Output to stdout (useful for CI/CD and containers)
mssql_python.setup_logging(output="stdout")

# Output to both file and stdout
mssql_python.setup_logging(output="both")

# Custom log file path (must use .txt, .log, or .csv extension)
mssql_python.setup_logging(log_file_path="/var/log/myapp/mssql.log")

Os arquivos de log usam o formato CSV e são rotacionados automaticamente ao atingirem 512 MB, mantendo cinco backups. O driver limpa dados sensíveis, como senhas e tokens de acesso, na saída de log.

Para adicionar entradas de aplicação ao log do driver, use driver_logger:

import mssql_python
from mssql_python.logging import driver_logger

mssql_python.setup_logging()

driver_logger.debug("[App] Starting data processing")
driver_logger.error("[App] Failed to process record")

Cuidado

O registro em log gera uma sobrecarga de desempenho. Ative isso apenas quando você resolver um problema. Não ative isso por padrão em produção.

Obtenha informações sobre o motorista

Recupere a versão do driver e os detalhes do servidor de uma conexão ativa:

import mssql_python

conn = mssql_python.connect(connection_string)

print(f"Version: {mssql_python.__version__}")
print(f"Server name: {conn.getinfo(mssql_python.SQL_SERVER_NAME)}")
print(f"Database name: {conn.getinfo(mssql_python.SQL_DATABASE_NAME)}")

Verificar o estado da conexão

Execute uma consulta leve para testar se uma conexão ainda está aberta:

import mssql_python

try:
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
    print("Connection is open")
except mssql_python.Error:
    print("Connection is closed or broken")

Referência rápida: Erros comuns

Erro SQLSTATE Causa comum Resolução de problemas
O cliente não consegue estabelecer conexão 08001 Servidor inacessível Não consigo conectar ao servidor
Falha no logon 28000 Credenciais incorretas Falha no login
Tempo limite expirado HYT00 ou HYT01 Rede lenta Tempo limite da conexão
Nome de objeto inválido 42S02 Tabela ou esquema incorreto Tabela ou objeto não encontrado
Erro de sintaxe 42000 Erro SQL Erro de sintaxe
Violação de restrição 23000 Violação de chave estrangeira ou chave primária Violações de restrições durante a cópia de massa
Deadlock 40001 Contenção de bloqueio Erros de bloqueio

Conteúdo relacionado

  • Last updated on