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.

Exception Wanneer deze wordt verhoogd
Warning Niet-dodelijke waarschuwingen uit de database.
Error Basisklasse voor alle databasefouten.
InterfaceError Fouten gerelateerd aan de database-interface (driver), niet aan de database zelf.
DatabaseError Fouten gerelateerd aan de database.
DataError Fouten door problemen met verwerkte data (delen door nul, waarde buiten bereik).
OperationalError Fouten gerelateerd aan databasewerking (verbinding verloren, geheugentoewijzing, transactiefouten).
IntegrityError Fouten wanneer de integriteit van de database wordt beïnvloed (vreemde sleutelschending, unieke beperking).
InternalError Interne databasefouten (cursor niet geldig, transactie niet synchroon).
ProgrammingError Programmeerfouten (syntaxisfouten, tabel niet gevonden, verkeerd aantal parameters).
NotSupportedError Functie die niet wordt ondersteund door de database of driver.
ConnectionStringParseError Ongeldige verbindingsreeks-syntaxis of onbekende trefwoorden.

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:

Attribute Source Beschrijving
driver_error Python-driver Gestandaardiseerde Engelse tekst gekozen door de SQLSTATE die uit ODBC werd teruggegeven (bijvoorbeeld "Communication link failure", "Invalid authorization specification", ). "Syntax error or access violation" Stabiel over releases heen; Veilig om substring-matchen te maken.
ddbc_error Directe databaseconnectiviteit (DDBC) Het server-side bericht, meestal voorafgegaan door [Microsoft][SQL Server]. Format is geen stabiel contract.
message Samengesteld uit f"Driver Error: {driver_error}; DDBC Error: {ddbc_error}". Dit is wat str(exc) terugkomt. 
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

SQLSTATE Exception Beschrijving
00000 None Success

Klasse 01 - Waarschuwing

SQLSTATE Exception Beschrijving
01000 Warning Algemene waarschuwing
01001 Warning Conflict met cursorbewerking
01002 Warning Ontkoppelingsfout
01003 DataError NULL-waarde geëlimineerd in setfunctie
01004 DataError Tekenreeksgegevens, rechts afkappen
01006 Warning Bevoegdheid niet ingetrokken
01007 Warning Bevoegdheid niet verleend
01S00 Warning Ongeldige verbindingsreeks-attribuut
01S01 Warning Fout in rij
01S02 Warning Optiewaarde gewijzigd

Klasse 07 - Dynamische SQL-fout

SQLSTATE Exception Beschrijving
07001 ProgrammingError Verkeerd aantal parameters
07002 ProgrammingError VELD AANTAL is onjuist
07005 ProgrammingError Prepared statement, geen cursor-specificatie
07006 ProgrammingError Schending van kenmerk van beperkt gegevenstype
07009 ProgrammingError Ongeldige descriptorindex
07S01 ProgrammingError Ongeldig gebruik van standaardparameter

Klasse 08 - Aansluitingsuitzondering

SQLSTATE Exception Beschrijving
08001 OperationalError Client kan geen verbinding tot stand brengen
08002 OperationalError Verbindingsnaam in gebruik
08003 OperationalError Verbinding bestaat niet
08004 OperationalError Server weigerde de verbinding
08007 OperationalError Verbindingsstoring tijdens transactie
08S01 OperationalError Communicatiekoppelingsfout

Klasse 21 - Cardinaliteitsschending

SQLSTATE Exception Beschrijving
21S01 ProgrammingError Lijst met waarden invoegen komt niet overeen met de kolomlijst
21S02 ProgrammingError De mate van afgeleide tabel komt niet overeen met de kolomlijst

Klasse 22 - Gegevensuitzondering

SQLSTATE Exception Beschrijving
22001 DataError Tekenreeksgegevens, rechts afkappen
22002 DataError Indicatorvariabele vereist, maar niet opgegeven
22003 DataError Numerieke waarde buiten het bereik
22007 DataError Ongeldige datum/tijd-notatie
22008 DataError Overloop van datum/tijdveld
22012 DataError Delen door nul
22015 DataError Intervalveldoverloop
22018 DataError Ongeldige tekenwaarde voor cast-specificatie
22019 DataError Ongeldig escape-teken
22025 DataError Ongeldige escapereeks
22026 DataError Tekenreeksgegevens, lengte komt niet overeen

Klasse 23 - Schending van integriteitsbeperkingen

SQLSTATE Exception Beschrijving
23000 IntegrityError Schending van integriteitsbeperkingen (algemeen)

Klasse 24 - Ongeldige cursortoestand

SQLSTATE Exception Beschrijving
24000 Interne fout Ongeldige cursorstatus

Klasse 25 - Ongeldige transactietoestand

SQLSTATE Exception Beschrijving
25000 OperationalError Ongeldige transactietoestand
25S01 OperationalError Transactietoestand onbekend
25S02 OperationalError De transactie is nog steeds actief
25S03 OperationalError De transactie wordt teruggedraaid

Klasse 28 - Ongeldige autorisatiespecificatie

SQLSTATE Exception Beschrijving
28000 OperationalError Ongeldige autorisatiespecificatie (login mislukt)

Klasse 34 - Ongeldige cursornaam

SQLSTATE Exception Beschrijving
34000 ProgrammingError Ongeldige cursornaam

Klasse 3C - Dubbele cursornaam

SQLSTATE Exception Beschrijving
3C000 ProgrammingError Dubbele cursornaam

Klasse 3D - Ongeldige catalogusnaam

SQLSTATE Exception Beschrijving
3D000 ProgrammingError Ongeldige catalogusnaam

Klasse 3F - Ongeldige schemanaam

SQLSTATE Exception Beschrijving
3F000 ProgrammingError Ongeldige schemanaam

Klasse 40 - Transactie-terugrol

SQLSTATE Exception Beschrijving
40001 OperationalError Serialisatiefout (deadlock)
40002 OperationalError Overtreding van integriteitsbeperkingen veroorzaakte rollback
40003 OperationalError Voltooiing van instructie onbekend

Klasse 42 - Syntaxisfout of overtreding van toegangsregels

SQLSTATE Exception Beschrijving
42000 ProgrammingError Syntaxisfout of schending van toegang
42S01 ProgrammingError Basistabel of -weergave bestaat al
42S02 ProgrammingError Basistabel of -weergave is niet gevonden
42S11 ProgrammingError Index bestaat al
42S12 ProgrammingError Index is niet gevonden
42S21 ProgrammingError Kolom bestaat al
42S22 ProgrammingError Kolom is niet gevonden

Class 44 - MET CHECK-OPTIE overtreding

SQLSTATE Exception Beschrijving
44000 IntegrityError MET SCHENDING VAN CHECK OPTION

Klasse HY - CLI-specifieke aandoening

SQLSTATE Exception Beschrijving
HY000 DatabaseError Algemene fout
HY001 OperationalError Fout bij geheugentoewijzing
HY003 ProgrammingError Ongeldig type applicatiebuffer
HY004 ProgrammingError Ongeldig SQL-datatype
HY007 ProgrammingError De bijbehorende verklaring is niet voorbereid
HY008 OperationalError Bewerking geannuleerd
HY009 ProgrammingError Ongeldig gebruik van null-aanwijzer
HY010 ProgrammingError Fout in functiereeks
HY011 ProgrammingError Attribuut kan nu niet worden ingesteld
HY012 ProgrammingError Ongeldige transactie-operatiecode
HY013 OperationalError Fout bij geheugenbeheer
HY014 OperationalError Limiet op het aantal overschreden handles
HY015 ProgrammingError Geen cursornaam beschikbaar
HY016 ProgrammingError Kan een implementatie-rijdescriptor niet wijzigen
HY017 ProgrammingError Ongeldig gebruik van automatisch toegewezen descriptorhandle
HY018 OperationalError Server weigerde annuleringsverzoek
HY019 ProgrammingError Niet-karakter- en niet-binaire gegevens die in stukken worden verzonden
HY020 DataError Poging om een nulwaarde te concateneren
HY021 ProgrammingError Inconsistente beschrijvingsinformatie
HY024 ProgrammingError Ongeldige kenmerkwaarde
HY090 ProgrammingError Ongeldige tekenreeks- of bufferlengte
HY091 ProgrammingError Ongeldige descriptorveldidentificatie
HY092 ProgrammingError Ongeldige attribuut/optie-identificatie
HY095 ProgrammingError Functietype buiten bereik
HY096 ProgrammingError Ongeldig informatietype
HY097 ProgrammingError Kolomtype buiten bereik
HY098 ProgrammingError Scope type buiten bereik
HY099 ProgrammingError Nulbaar type buiten bereik
HY100 ProgrammingError Type uniekheidsoptie buiten bereik
HY101 ProgrammingError Type nauwkeurigheidsoptie buiten bereik
HY103 ProgrammingError Ongeldige ophaalcode
HY104 ProgrammingError Ongeldige precisie of schaalwaarde
HY105 ProgrammingError Ongeldig parametertype
HY106 ProgrammingError Haal het type buiten bereik
HY107 ProgrammingError Rijwaarde buiten bereik
HY109 ProgrammingError Ongeldige cursorpositie
HY110 ProgrammingError Ongeldige drivervoltooiing
HY111 ProgrammingError Ongeldige bladwijzerwaarde
HYC00 NotSupportedError Optionele functie niet geïmplementeerd
HYT00 OperationalError Time-out verlopen
HYT01 OperationalError Time-out voor de verbinding is overschreden

Klasse IM - Driver manager fout

SQLSTATE Exception Beschrijving
IM001 InterfaceError Stuurprogramma biedt geen ondersteuning voor deze functie
IM002 InterfaceError Naam van de gegevensbron niet gevonden
IM003 InterfaceError De opgegeven driver kon niet worden geladen
IM004 InterfaceError De SQLAllocHandle van de driver op SQL_HANDLE_ENV faalde
IM005 InterfaceError De SQLAllocHandle van de driver op SQL_HANDLE_DBC faalde
IM006 InterfaceError De driver's SQLSetConnectAttr faalde
IM007 InterfaceError Geen databron of driver gespecificeerd
IM008 InterfaceError Dialoog mislukte
IM009 InterfaceError Vertaaldll kan niet laden
IM010 InterfaceError Naam van de gegevensbron is te lang
IM011 InterfaceError Rijdersnaam te lang
IM012 InterfaceError DRIVER sleutelwoordsyntaxis fout
IM014 InterfaceError Ongeldig DSN
IM015 InterfaceError Corrupte bestandsgegevensbron

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

Fout Berichtpatroon Resolutie
208 Ongeldige objectnaam Controleer of de tabel of view bestaat en controleer de schema-kwalificatie.
547 Beperkingsschending Een vreemde sleutel of controlebeperking faalde.
2627 Unieke constraint-schending Er werd een dubbele sleutelwaarde toegevoegd.
2601 Unieke indexbreuk Er bestaat een dubbele sleutel in de index.
4060 Kan database niet openen De database bestaat niet of toegang wordt geweigerd.
18456 Aanmelden is mislukt Authenticatiefout. Controleer de gegevens.
1205 Het slachtoffer van de impasse De transactie is teruggedraaid. Voer de bewerking opnieuw uit.

Symptoom-naar-uitzondering snelle referentie

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

Symptom Exception Waarschijnlijke oorzaak
"Login mislukt voor gebruiker" OperationalError Verkeerde inloggegevens of gebruiker niet toegewezen aan de database.
"Cliënt kan geen verbinding tot stand brengen" OperationalError Server onbereikbaar, firewall of DNS-probleem.
"Time-out is verlopen" OperationalError Query of verbindingstime-out. Verhoog de timeout of optimaliseer de query.
"Ongeldige objectnaam" ProgrammingError Tabel bestaat niet of schema niet gespecificeerd.
"Onjuiste syntaxis" ProgrammingError SQL-syntaxisfout. Testquery in SSMS.
"Verkeerd aantal parameters" ProgrammingError Het aantal parameters komt niet overeen met tijdelijke aanduidingen.
"Overtreding van PRIMAIRE SLEUTEL" IntegrityError Dubbele sleutel. Gebruik MERGE of controleer voordat je het inbrengt.
"Overtreding van VREEMDE SLEUTEL" IntegrityError Referent row bestaat niet. Eerst ouder invoegen.
"Transactie was vastgelokt" OperationalError (fout 1205) Vergrendel de concurrentie. Implementeer logica voor opnieuw proberen.
"String- of binaire data zou worden afgekapt" DataError De waarde overschrijdt kolomlengte. Controleer de data of verhoog de kolomgrootte.
"Conversie mislukt" DataError Type komt niet overeen. Gebruik het juiste Python-type voor de kolom.
"Onbekend trefwoord" ConnectionStringParseError Typefout in het verbindingsreeks-zoekwoord.
"callproc wordt niet ondersteund" NotSupportedError Gebruik in plaats daarvan cursor.execute("EXECUTE ...").

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

  • Last updated on