Resolução de problemas de mssql-python

Utilize este artigo para encontrar orientações de resolução de problemas para o mssql-python condutor. Começa pelo sintoma ou mensagem de erro que corresponde ao teu problema.

Problemas de instalação

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

Para versões de Python não suportadas, rodas em falta, ambientes virtuais inativos e bibliotecas Linux em falta, consulte Resolução de problemas de instalação e ligação.

Instalações de drivers conflitantes

Para erros de importação ou comportamentos inesperados quando mssql-python e pyodbc são instalados em conjunto, consulte Resolução de problemas de instalação e ligação.

Problemas de conexão

Impossível ligar-se ao servidor

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

Início de sessão falhado

Para SQLSTATE 28000, incompatibilidades no modo de autenticação, credenciais inválidas e utilizadores de base de dados em falta, consulte Resolução de problemas de instalação e ligação.

Tempo limite de ligação

Para SQLSTATE HYT00 ou HYT01, latência de rede, servidores lentos e definições de tempo limite de ligação, consulte Resolução de problemas de instalação e ligação.

Erros de certificado SSL

Para erros de certificado não confiáveis e opções seguras de desenvolvimento local, consulte Resolução de problemas de instalação e ligação.

Problemas de execução de consultas

Tabela ou objeto não encontrado

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

Erro de sintaxe

Para SQLSTATE 42000, sintaxe SQL, escape de strings e consultas parametrizadas, veja Resolução de problemas de consulta, dados e operações.

Erros de parâmetros

Para os SQLSTATE 07001, o número de marcadores de posição e os estilos de parâmetros suportados, consulte Resolver problemas de consultas, dados e operações.

Problemas de tipo de dados

Erros de conversão de data e hora

Para SQLSTATE 22007 e conversão de parâmetros de data e hora, veja Resolução de problemas de consultas, dados e operações.

Questões de precisão decimal

Para valores decimais truncados ou arredondados, veja Resolução de problemas de consulta, dados e operação.

Problemas de codificação Unicode

Para caracteres especiais distorcidos e tipos de colunas Unicode, consulte Troubleshoot query, data, and operation issues.

Problemas de desempenho

Execução lenta da consulta

Para indexação, grandes conjuntos de resultados e agregação de ligações, veja Resolver problemas de consultas, dados e operações.

Problemas de memória com resultados de grande dimensão

Para transmissão em fluxo e paginação de conjuntos de resultados extensos, consulte Resolver problemas de consultas, dados e operações.

Questões de transação

Âmbito da tabela temporária com autocommit

Para obter informações sobre tabelas temporárias que desaparecem após o rollback e instruções DDL que exigem autocommit, veja Resolver problemas de consultas, dados e operações.

Transação não comprometida

Para alterações de dados que não persistem após o encerramento da ligação, veja Resolução de problemas de consulta, dados e operações.

Erros de bloqueio

Para SQLSTATE 40001, orientações sobre novas tentativas e análise de deadlocks recorrentes, consulte Resolver problemas de consultas, dados e operações.

Problemas de carregamento em massa

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

Em caso de violações de chave primária, de exclusividade, de verificação ou de chave estrangeira durante a cópia em massa, consulte Resolução de problemas de consultas, dados e operações.

Erros de mapeamento de colunas

Para incompatibilidades no número de colunas e na ordem das colunas na cópia em massa, consulte Resolver problemas de consultas, dados e operações.

Desajustes de tipo durante a cópia em massa

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

Falhas de ligação do tipo NumPy

Para falhas na associação de parâmetros com tipos inteiros ou de vírgula flutuante do NumPy, veja Resolver problemas de consulta, dados e operações.

Cópia em massa com tabelas temporárias

Relativamente aos erros Invalid object name ao utilizar bulkcopy() com uma tabela temporária de sessão, consulte Resolução de problemas de consulta, dados e operação.

Questões de contentores e CI

Bibliotecas de sistema em falta no Linux

Para a falta de libltdl ou de bibliotecas Kerberos em ambientes Linux, consulte Resolver problemas de instalação e ligação.

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

Para erros relacionados com SSL no macOS, incluindo o Apple Silicon, consulte Resolução de problemas de instalação e ligação.

Ferramentas de diagnóstico

Ativar o registo do controlador

Use mssql_python.setup_logging() para ativar o registo DEBUG. O driver regista instruções SQL, parâmetros, operações ODBC internas e alterações no estado da ligaçã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 ficheiros de registo utilizam o formato CSV e são rodados automaticamente ao atingirem 512 MB, com cinco cópias de segurança. O driver remove dados sensíveis, como palavras-passe e tokens de acesso, dos registos.

Para adicionar entradas de aplicação ao registo do driver, utilize 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")

Obtenha informações sobre o condutor

Recupere a versão do driver e os dados do servidor de uma ligaçã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 ligação

Execute uma consulta leve para testar se uma ligaçã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

Conteúdo relacionado

• Gestão de erros e códigos SQLSTATE para mssql-python
• Strings de ligação para mssql-python
• Agregação de ligações com mssql-python
• problemas do GitHub