Fehlerbehandlung und SQLSTATE-Codes für mssql-python

Der mssql-python-Treiber definiert eine Standard-Ausnahmehierarchie, häufige Fehlerbehandlungsmuster und SQLSTATE-Codezuordnungen für SQL Server und Azure SQL.

Ausnahmehierarchie

Der mssql-python-Treiber folgt der DB-API 2.0 (PEP 249) Ausnahmehierarchie:

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

ConnectionStringParseError (standalone, not part of hierarchy)

Ausnahmebeschreibungen

Fange die spezifischste Ausnahme, die zu deiner Situation passt. Zum Beispiel bei IntegrityError Einschränkungsverletzungen bei INSERT/UPDATE Operationen und ProgrammingError bei SQL-Syntaxproblemen während der Entwicklung erkennen. Fang die Basisklasse Error nur als Rückfall.

Grundlegende Fehlerbehandlung

Verwenden Sie Try-Only-Blöcke, um Datenbankfehler zu behandeln:

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

Zugriffsausnahmen über die Verbindung

Sie können Ausnahmen über die Verbindungsinstanz erkennen:

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

Fehlermeldungsstruktur

MSSQL-Python-Ausnahmeobjekte stellen drei Attribute frei, die aus der Exception Basisklasse des Treibers stammen:

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

Die Fehlernummer der SQL Server-Engine (wie 208 oder 40501) wird nicht als Attribut angezeigt und ist in keinem der beiden Strings zuverlässig eingebettet. Klassifiziere Fehler nach Ausnahme-Unterklasse plus driver_error Text. Für Azure SQL Throttling siehe Retry Logic.

SQLSTATE-Klassifikation

mssql-python verwendet den von ODBC zurückgegebenen SQLSTATE, um sowohl die Python-Ausnahme-Unterklasse als auch den driver_error Text auszuwählen. Das vollständige SQLSTATE-→ Ausnahmemapping ist im Treibercode enthalten exceptions.py . Der nächste Abschnitt listet die SQLSTATES auf, die am häufigsten bei SQL Server und Azure SQL auftreten.

Verbindungsfehler

Verbindungsfehler von mssql_python.connect() Raise mssql_python.OperationalError, wie bei anderen Konnektivitätsfehlern:

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"

Verbindungsstring-Fehler

Fehler bei der Parsing von Verbindungsstrings führen zu 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-Codereferenz

SQLSTATE-Codes sind fünfstellige Codes, die Fehlerbedingungen identifizieren. Die ersten beiden Zeichen zeigen die Klasse an, die letzten drei die Unterklasse. Sie müssen diese Vorschriften selten direkt inspizieren. Stattdessen fangen Sie den entsprechenden Python-Ausnahmetyp ab (aufgeführt in der Spalte "Ausnahme"). Verwenden Sie SQLSTATE-Codes, wenn Sie zwischen bestimmten Fehlerzuständen innerhalb desselben Ausnahmetyps unterscheiden müssen, zum Beispiel um einen Deadlock (40001) von einem allgemeinen Verbindungsfehler (08S01) zu unterscheiden.

Baureihe 00 – Erfolgreicher Abschluss

Baureihe 01 – Warnung

Klasse 07 – Dynamischer SQL-Fehler

Baureihe 08 – Verbindungsausnahme

Klasse 21 – Kardinalitätsverletzung

Klasse 22 – Datenausnahme

Klasse 23 – Verletzung der Integritätsbedingung

Klasse 24 – Ungültiger Cursorzustand

Klasse 25 – Ungültiger Transaktionszustand

Klasse 28 – Ungültige Autorisierungsspezifikation

Klasse 34 – Ungültiger Cursorname

Klasse 3C – Name des doppelten Cursors

Klasse 3D – Ungültiger Katalogname

Klasse 3F – Ungültiger Schemaname

Klasse 40 – Transaktionsrückgang

Klasse 42 – Syntaxfehler oder Zugriffsregelverletzung

Klasse 44 – MIT CHECK-OPTION Verstoß

Klasse HY – CLI-spezifische Bedingung

Klassen-IM – Fehler im Treibermanager

Häufige SQL Server-Fehlernummern

Über SQLSTATE hinaus stellt SQL Server native Fehlernummern in Klammern bereit. Das sind die Fehler, denen Sie am wahrscheinlichsten im Anwendungscode begegnen werden. Baue die Retry-Logik um Fehler 1205 (Deadlock) und transiente Verbindungsfehler (siehe Retry-Logik).

Schnellreferenz von Symptom zu Ausnahme

Verwenden Sie diese Tabelle, um häufige Symptome dem Ausnahmetyp zuzuordnen, den Sie fangen sollten:

Bewährte Methoden

• Fangen Sie bestimmte Ausnahmen vor generischen Ausnahmen. Ordne von am spezifischsten (IntegrityError) bis am wenigsten spezifischen (Error).
• Behandle IntegrityError immer für Datenmodifikationsoperationen. Einschränkungsverletzungen werden im normalen Betrieb erwartet (zum Beispiel wenn ein Benutzer versucht, einen doppelten Benutzernamen zu erstellen).
• Protokolliere den vollständigen Fehlerkontext zur Fehlersuche. Die Ausnahme stellt driver_error (stabilen, SQLSTATE-abgeleiteten Text) und ddbc_error (serverseitige Nachricht) frei. Beide protokollieren; klassifizieren auf driver_error.
• Retry-Logik für vorübergehende Fehler (Verbindungsausfälle, Deadlocks) implementieren. Siehe Logik für Wiederholen.
• Verwenden Sie Rollback() in Ausnahmehandlern, um fehlgeschlagene Transaktionen zu bereinigen. Ohne explizite Rollback bleibt die Verbindung im Zustand einer fehlgeschlagenen Transaktion.

Verwandte Inhalte

• Handbuch zur Problembehandlung
• Abfragen ausführen
• Verbindungsverwaltung