Foutafhandeling en SQLSTATE-codes voor mssql-python

De mssql-python-driver definieert een standaard uitzonderingshiërarchie, veelvoorkomende foutafhandelingspatronen en SQLSTATE-codetoewijzingen voor SQL Server en Azure SQL.

Uitzonderingshiërarchie

De mssql-python-driver volgt de DB-API 2.0 (PEP 249) uitzonderingshiërarchie:

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

ConnectionStringParseError (standalone, not part of hierarchy)

Uitzonderingsbeschrijvingen

Pak de meest specifieke uitzondering die bij jouw situatie past. Bijvoorbeeld, vang IntegrityError op constraint-overtredingen op INSERT/UPDATE operaties, en ProgrammingError op SQL-syntaxproblemen tijdens de ontwikkeling. Pak de basisklasse Error alleen als een back-back.

Basisfoutbehandeling

Gebruik try-excuse-blokken om databasefouten te verwerken:

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

Toegang tot uitzonderingen via de verbinding

Je kunt uitzonderingen vangen via de verbindingsinstantie:

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

Structuur van foutmeldingen

MSSQL-Python uitzonderingsobjecten tonen drie attributen die afkomstig zijn van de Exception basisklasse van de 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: ...

Het foutnummer van de SQL Server-engine (zoals 208 of 40501) wordt niet als attribuut getoond en is niet betrouwbaar in een van beide strings ingebed. Classificeer fouten per uitzonderingssubklasse plus driver_error tekst. Voor Azure SQL throttling, zie Retry logic.

SQLSTATE-classificatie

mssql-python gebruikt de SQLSTATE die door ODBC wordt teruggegeven om zowel de Python-uitzonderingsubklasse als de driver_error tekst te kiezen. De volledige SQLSTATE-→ exception mapping staat in exceptions.py de driverbroncode. De volgende sectie geeft een overzicht van de SQLSTATES die het vaakst voorkomen bij SQL Server en Azure SQL.

Verbindingsfouten

Verbindingsfouten van mssql_python.connect() raise mssql_python.OperationalError, hetzelfde als andere connectiviteitsstoringen:

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"

Verbindingsreeksfouten

Fouten bij het parsen van verbindingsstrings verhogen 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'

SQLSTATE-codereferentie

SQLSTATE-codes zijn vijf-tekens codes die foutvoorwaarden identificeren. De eerste twee tekens geven de klasse aan, en de laatste drie geven de subklasse aan. Je hoeft deze codes zelden direct te inspecteren. Vang in plaats daarvan het juiste Python-uitzonderingstype (vermeld in de kolom "Uitzondering"). Gebruik SQLSTATE-codes wanneer je specifieke foutvoorwaarden binnen hetzelfde uitzonderingstype moet onderscheiden, bijvoorbeeld om een deadlock (40001) te onderscheiden van een algemene verbindingsfout (08S01).

Klasse 00 - Succesvolle voltooiing

Klasse 01 - Waarschuwing

Klasse 07 - Dynamische SQL-fout

Klasse 08 - Aansluitingsuitzondering

Klasse 21 - Cardinaliteitsschending

Klasse 22 - Gegevensuitzondering

Klasse 23 - Schending van integriteitsbeperkingen

Klasse 24 - Ongeldige cursortoestand

Klasse 25 - Ongeldige transactietoestand

Klasse 28 - Ongeldige autorisatiespecificatie

Klasse 34 - Ongeldige cursornaam

Klasse 3C - Dubbele cursornaam

Klasse 3D - Ongeldige catalogusnaam

Klasse 3F - Ongeldige schemanaam

Klasse 40 - Transactie-terugrol

Klasse 42 - Syntaxisfout of overtreding van toegangsregels

Class 44 - MET CHECK-OPTIE overtreding

Klasse HY - CLI-specifieke aandoening

Klasse IM - Driver manager fout

Veelvoorkomende SQL Server-foutnummers

Naast SQLSTATE biedt SQL Server native foutnummers tussen haakjes. Dit zijn de fouten die je het meest waarschijnlijk zult tegenkomen in applicatiecode. Bouw herprobeerlogica rond fout 1205 (deadlock) en tijdelijke verbindingsfouten (zie Herprobeerlogica).

Symptoom-naar-uitzondering snelle referentie

Gebruik deze tabel om veelvoorkomende symptomen toe te wijzen op het uitzonderingstype dat je zou moeten vangen:

Beste praktijken

• Vang specifieke uitzonderingen voordat je generieke uitzonderingen hebt. Bestel van meest specifiek (IntegrityError) tot minst specifiek (Error).
• Behandel altijd IntegrityError voor data-aanpassingsoperaties. Constraint-overtredingen worden verwacht in normale werking (bijvoorbeeld een gebruiker die probeert een dubbele gebruikersnaam aan te maken).
• Log de volledige foutcontext voor het oplossen van problemen. De uitzondering maakt driver_error (stabiele, SQLSTATE-afgeleide tekst) en ddbc_error (server-side bericht) beschikbaar. Log beide; classificeer op driver_error.
• Implementeer herprobeerlogica voor tijdelijke fouten (verbindingsfouten, deadlocks). Zie Herzien Proberen Logica.
• Gebruik rollback() in exception handlers om mislukte transacties op te schonen. Zonder expliciete terugrol blijft de verbinding in een fail-transactietoestand.

Verwante onderwerpen

• Gids voor probleemoplossing
• Voer queries uit
• Verbindingsbeheer