Gestion des erreurs et codes SQLSTATE pour mssql-python

Le pilote mssql-python définit une hiérarchie d’exception standard, des schémas courants de gestion des erreurs et des correspondances de code SQLSTATE pour SQL Server et Azure SQL.

Hiérarchie d’exceptions

Le pilote mssql-python suit la hiérarchie des exceptions DB-API 2.0 (PEP 249) :

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

ConnectionStringParseError (standalone, not part of hierarchy)

Descriptions des exceptions

Identifiez l’exception la plus spécifique qui correspond à votre situation. Par exemple, détecter IntegrityError les violations de contraintes sur INSERT/UPDATE operations, et ProgrammingError les problèmes de syntaxe SQL pendant le développement. Ne prends la classe de Error base qu’en plan B.

Gestion des erreurs de base

Utilisez des blocs try-except pour gérer les erreurs de base de données :

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

Accès aux exceptions via la connexion

Vous pouvez détecter des exceptions via l’instance de connexion :

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

Structure des messages d’erreur

Les objets d’exception MSSQL-Python exposent trois attributs provenant de la classe de base duException pilote :

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

Le numéro d'erreur du moteur SQL Server (comme 208 ou 40501) n'est pas exposé comme attribut et n'est pas intégré de manière fiable dans aucune des chaînes. Classez les erreurs par sous-classe d’exception plus driver_error le texte. Pour le throttling Azure SQL, voir Logique de réessayage.

Classification SQLSTATE

mssql-python utilise l’état SQLSTATE retourné par ODBC pour choisir à la fois la sous-classe d’exception Python et le driver_error texte. Le SQLSTATE complet → la correspondance des exceptions se trouve exceptions.py dans le code source du pilote. La section suivante énumère les SQLSTATE qui apparaissent le plus souvent avec SQL Server et Azure SQL.

Erreurs de connexion

Les défaillances de connexion dues mssql_python.connect() au relance mssql_python.OperationalError, identiques à celles des autres défaillances de connectivité :

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"

Erreurs de chaîne de connexion

Les erreurs d’analyse syntaxique de chaînes de connexion entraînent 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'

Référence du code SQLSTATE

Les codes SQLSTATE sont des codes de cinq caractères qui identifient les conditions d’erreur. Les deux premiers caractères indiquent la classe, et les trois derniers la sous-classe. Vous avez rarement besoin d’inspecter ces codes directement. À la place, sélectionnez le type d’exception Python approprié (indiqué dans la colonne « Exception »). Utilisez des codes SQLSTATE lorsque vous devez distinguer des conditions d’erreur spécifiques au sein d’un même type d’exception, par exemple pour différencier un deadlock (40001) d’une défaillance générale de connexion (08S01).

Classe 00 - Réussite

Classe 01 - Avertissement

Classe 07 - Erreur SQL dynamique

Classe 08 - Exception de connexion

Classe 21 - Violation de cardinalité

Classe 22 - Exception de données

Classe 23 - Violation des contraintes d’intégrité

Classe 24 - État du curseur invalide

Classe 25 - État de transaction invalide

Classe 28 - Spécification d’autorisation invalide

Classe 34 - Nom de curseur invalide

Classe 3C - Nom de curseur dupliqué

Classe 3D - Nom de catalogue invalide

Classe 3F - Nom de schéma invalide

Classe 40 - Annulation de transaction

Classe 42 - Erreur de syntaxe ou violation de la règle d’accès

Classe 44 - VIOLATION DE L’OPTION DE VÉRIFICATION

Classe HY - Condition spécifique à CLI

Classe IM - Erreur du manager du pilote

Numéros d’erreur courants sur SQL Server

Au-delà de SQLSTATE, SQL Server fournit des numéros d’erreur natifs entre parenthèses. Ce sont les erreurs que vous êtes le plus susceptible de rencontrer dans le code de l’application. Construire la logique de réessai autour de l’erreur 1205 (blocage) et des erreurs de connexion transitoires (voir logique de réessayage).

Référence rapide des symptômes à l’exception

Utilisez ce tableau pour associer les symptômes courants au type d’exception que vous devriez détecter :

Bonnes pratiques

• Prenez les exceptions spécifiques avant les génériques. Ordre du plus spécifique (IntegrityError) au moins spécifique (Error).
• Gérez toujours IntegrityError pour les opérations de modification des données. Les violations de contraintes sont attendues en fonctionnement normal (par exemple, un utilisateur essayant de créer un nom d’utilisateur en double).
• Enregistrez le contexte complet des erreurs pour le dépannage. L’exception expose driver_error (texte stable, dérivé de SQLSTATE) et ddbc_error (message côté serveur). Enregistrez les deux ; classifier sur driver_error.
• Implémentez une logique de réévaluation pour les erreurs transitoires (pannes de connexion, blocages). Voir logique de réessayage.
• Utilisez rollback() dans les gestionnaires d’exceptions pour corriger les transactions ratées. Sans retour explicite, la connexion reste dans un état de transaction échouée.

Contenu connexe

• Guide de résolution des problèmes
• Exécution des requêtes
• Gestion des connexions