Gestão de erros e códigos SQLSTATE para mssql-python

O driver mssql-python define uma hierarquia padrão de exceções, padrões comuns de tratamento de erros e mapeamentos de código SQLSTATE para SQL Server e SQL do Azure.

Hierarquia de exceção

O driver mssql-python segue a hierarquia de exceções DB-API 2.0 (PEP 249):

Exception (builtins)
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError

ConnectionStringParseError (standalone, not part of hierarchy)

Descrições de exceções

Apanha a exceção mais específica que corresponda à sua situação. Por exemplo, apanhar IntegrityError violações de restrições em INSERToperações/UPDATE , e ProgrammingError para problemas de sintaxe SQL durante o desenvolvimento. Apanhar a classe base Error apenas como plano B.

Gestão básica de erros

Use blocos try-except para lidar com erros na base de dados:

import mssql_python

try:
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("INSERT INTO Production.Product (Name) VALUES (%(name)s)", {"name": "Test"})
    conn.commit()
except mssql_python.IntegrityError as e:
    print(f"Constraint violation: {e}")
    conn.rollback()
except mssql_python.ProgrammingError as e:
    print(f"SQL syntax error: {e}")
except mssql_python.OperationalError as e:
    print(f"Connection or operational error: {e}")
except mssql_python.Error as e:
    print(f"Database error: {e}")
finally:
    if 'conn' in locals():
        conn.close()

Exceções de acesso através da ligação

Pode detetar exceções através da instância de ligação:

try:
    cursor.execute("INVALID SQL")
except conn.ProgrammingError as e:
    print(f"Caught via connection: {e}")

Estrutura da mensagem de erro

Os objetos de exceção mssql-python expõem três atributos que provêm da classe base doException driver:

try:
    cursor.execute("SELECT * FROM no_such_table;")
except mssql_python.ProgrammingError as exc:
    print(exc.driver_error)  # Base table or view not found
    print(exc.ddbc_error)    # [Microsoft][SQL Server]Invalid object name 'no_such_table'.
    print(exc)               # Driver Error: Base table or view not found; DDBC Error: ...

O número de erro do motor do SQL Server (como 208 ou 40501) não é exposto como um atributo e não está embutido de forma fiável em nenhuma das strings. Classificar erros por subclasse de exceção mais driver_error texto. Para o throttling do SQL do Azure, veja Retry logic.

Classificação SQLSTATE

mssql-python usa o SQLSTATE devolvido pelo ODBC para escolher tanto a subclasse de exceção Python como o driver_error texto. O mapeamento completo de SQLSTATE → exceções está no exceptions.py código-fonte do driver. A secção seguinte lista os SQLSTATEs que aparecem com mais frequência no SQL Server e no SQL do Azure.

Erros de ligação

Falhas de ligação do mssql_python.connect() raise mssql_python.OperationalError, iguais a outras falhas de conectividade:

import mssql_python

try:
    conn = mssql_python.connect(
        "Server=unreachable-server.database.windows.net;"
        "Database=<database>;"
        "Authentication=ActiveDirectoryDefault;"
        "Encrypt=yes"
    )
except mssql_python.OperationalError as e:
    print(f"Connection failed: {e.driver_error}")
    # e.driver_error: "Client unable to establish connection"

Erros na cadeia de ligação

Erros de análise sintática de stringas de ligação aumentam ConnectionStringParseError:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Referência de código SQLSTATE

Os códigos SQLSTATE são códigos de cinco caracteres que identificam condições de erro. Os dois primeiros caracteres indicam a classe, e os últimos três indicam a subclasse. Raramente precisa de inspecionar estes códigos diretamente. Em vez disso, escolha o tipo de exceção Python apropriado (listado na coluna "Exceção"). Use códigos SQLSTATE quando precisar de distinguir entre condições de erro específicas dentro do mesmo tipo de exceção, por exemplo, para diferenciar um deadlock (40001) de uma falha geral de ligação (08S01).

Classe 00 - Conclusão bem-sucedida

Classe 01 - Aviso

Classe 07 - Erro SQL dinâmico

Classe 08 - Exceção de ligação

Classe 21 - Violação de cardinalidade

Classe 22 - Exceção de dados

Classe 23 - Violação de restrições de integridade

Classe 24 - Estado do cursor inválido

Classe 25 - Estado de transação inválido

Classe 28 - Especificação de autorização inválida

Classe 34 - Nome do cursor inválido

Classe 3C - Nome duplicado do cursor

Classe 3D - Nome inválido do catálogo

Classe 3F - Nome inválido do esquema

Classe 40 - Reversão de transações

Classe 42 - Erro de sintaxe ou violação da regra de acesso

Classe 44 - VIOLAÇÃO DA OPÇÃO DE VERIFICAÇÃO

Classe HY - condição específica de CLI

Classe IM - Erro do gestor do piloto

Números de erro comuns do SQL Server

Para além do SQLSTATE, o SQL Server fornece números de erro nativos entre parênteses. Estes são os erros que é mais provável de encontrar no código da aplicação. Construir a lógica de retentativa em torno do erro 1205 (deadlock) e erros de ligação transitória (ver lógica de retentação).

Referência rápida de sintomas para exceções

Use esta tabela para mapear os sintomas comuns ao tipo de exceção que deverá detetar:

Melhores práticas

• Apanha exceções específicas antes das genéricas. Ordem do mais específico (IntegrityError) ao menos específico (Error).
• Manusei sempre o IntegrityError para operações de modificação de dados. Violações de restrições são esperadas em funcionamento normal (por exemplo, um utilizador a tentar criar um nome de utilizador duplicado).
• Regista o contexto completo do erro para a resolução de problemas. A exceção expõe driver_error (texto estável, derivado do SQLSTATE) e ddbc_error (mensagem do lado do servidor). Regista ambos; classificar em driver_error.
• Implementar lógica de retentativa para erros transitórios (falhas de ligação, bloqueios). Veja Lógica de Retentar.
• Use rollback() nos tratadores de exceções para limpar transações falhadas. Sem um rollback explícito, a ligação permanece num estado de transação falhada.

Conteúdo relacionado

• Guia de resolução de problemas
• Executar consultas
• Gestão de ligações