Gestione degli errori e codici SQLSTATE per mssql-python

Il driver mssql-python definisce una gerarchia standard di eccezioni, schemi comuni di gestione degli errori e mappature di codice SQLSTATE per SQL Server e Azure SQL.

Gerarchia delle eccezioni

Il driver mssql-python segue la gerarchia delle eccezioni DB-API 2.0 (PEP 249):

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

ConnectionStringParseError (standalone, not part of hierarchy)

Descrizioni delle eccezioni

Individua l'eccezione più specifica che si adatta alla tua situazione. Ad esempio, per le IntegrityError violazioni dei vincoli su INSERT/UPDATE operations e ProgrammingError per problemi di sintassi SQL durante lo sviluppo. Prendi la classe base Error solo come riserva.

Gestione di base degli errori

Usa i blocchi try-except per gestire errori nel database:

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()

Eccezioni di accesso tramite la connessione

Puoi individuare eccezioni tramite l'istanza di connessione:

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

Struttura del messaggio di errore

Gli oggetti eccezione mssql-python espongono tre attributi che provengono dalla classe base delException 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: ...

Il numero di errore del motore SQL Server (come 208 o 40501) non è esposto come attributo e non è incorporato in modo affidabile in nessuna delle due stringhe. Classifica gli errori per sottoclasse eccezione più driver_error testo. Per il throttling di Azure SQL, vedi Retry logic.

Classificazione SQLSTATE

mssql-python utilizza lo stato SQLSTATE restituito da ODBC per scegliere sia la sottoclasse eccezione Python sia il driver_error testo. La mappatura completa di SQLSTATE → eccezioni è presente exceptions.py nel driver source. La sezione successiva elenca gli stati SQL che appaiono più spesso con SQL Server e Azure SQL.

Errori di connessione

I guasti di connessione da mssql_python.connect() raise mssql_python.OperationalError, identici ad altri guasti di connettività:

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"

Errori della stringa di connessione

Gli errori di parsing delle stringhe di connessione aumentano 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'

Riferimento al codice SQLSTATE

I codici SQLSTATE sono codici di cinque caratteri che identificano le condizioni di errore. I primi due caratteri indicano la classe, e gli ultimi tre la sottoclasse. Raramente è necessario ispezionare direttamente questi codici. Invece, individua il tipo di eccezione Python appropriato (indicato nella colonna "Eccezione"). Usa i codici SQLSTATE quando devi distinguere tra specifiche condizioni di errore all'interno dello stesso tipo di eccezione, ad esempio per differenziare un deadlock (40001) da un guasto generale della connessione (08S01).

Classe 00 - Completamento con successo

Classe 01 - Avviso

Classe 07 - Errore SQL dinamico

Classe 08 - Eccezione per connessione

Classe 21 - Violazione della cardinalità

Classe 22 - Eccezione dati

Classe 23 - Violazione dei vincoli di integrità

Classe 24 - Stato del cursore invalido

Classe 25 - Stato della transazione invalido

Classe 28 - Specifica di autorizzazione invalida

Classe 34 - Nome cursore invalido

Classe 3C - Nome duplicato del cursore

Classe 3D - Nome del catalogo non valido

Classe 3F - Nome dello schema non valido

Classe 40 - Rollback delle transazioni

Classe 42 - Errore di sintassi o violazione della regola di accesso

Classe 44 - VIOLAZIONE DELL'OPZIONE CHECK

Classe HY - condizione specifica CLI

Classe MI - Errore del driver manager

Numeri di errore comuni di SQL Server

Oltre a SQLSTATE, SQL Server fornisce numeri di errore nativi tra parentesi. Questi sono gli errori che è più probabile che incontri nel codice applicativo. Costruire la logica di ritentazione attorno all'errore 1205 (bloccaggio) e agli errori di connessione transitoria (vedi logica di ritento).

Riferimento rapido da sintomo a eccezione

Usa questa tabella per mappare i sintomi comuni al tipo di eccezione che dovresti rilevare:

Procedure consigliate

• Individua eccezioni specifiche prima di quelle generiche. Ordina dal più specifico (IntegrityError) al meno specifico (Error).
• Gestisci sempre IntegrityError per le operazioni di modifica dei dati. Le violazioni dei vincoli sono attese nel funzionamento normale (ad esempio, un utente che cerca di creare un nome utente duplicato).
• Registra il contesto completo dell'errore per la risoluzione dei problemi. L'eccezione espone driver_error (testo stabile derivato da SQLSTATE) e ddbc_error (messaggio lato server). Registra entrambi; classificare su driver_error.
• Implementa la logica di ritentativi per errori transitori (guasti di connessione, bloccamenti). Vedi Logica di ritento.
• Usa rollback() nei gestori di eccezioni per pulire le transazioni fallite. Senza un rollback esplicito, la connessione rimane in uno stato di transazione fallita.

Contenuti correlati

• Guida per la risoluzione dei problemi
• Esecuzione delle query
• Gestione delle connessioni