Gestión de errores y códigos SQLSTATE para mssql-python

El controlador mssql-python define una jerarquía estándar de excepciones, patrones comunes de gestión de errores y mapeos de código SQLSTATE para SQL Server y Azure SQL.

Jerarquía de excepciones

El controlador mssql-python sigue la jerarquía de excepciones DB-API 2.0 (PEP 249):

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

ConnectionStringParseError (standalone, not part of hierarchy)

Descripciones de excepciones

Detecta la excepción más específica que se adapte a tu situación. Por ejemplo, detectar IntegrityError violaciones de restricciones en INSERT/UPDATE operaciones y ProgrammingError problemas de sintaxis SQL durante el desarrollo. Captura la clase base Error solo como plan B.

Gestión básica de errores

Utiliza bloques try-except para gestionar errores de base de datos:

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

Excepciones de acceso a través de la conexión

Puedes detectar excepciones a través de la instancia de conexión:

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

Estructura de mensajes de error

Los objetos de excepción mssql-python exponen tres atributos que provienen de la clase base delException controlador:

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

El número de error del motor de SQL Server (como 208 o 40501) no está expuesto como atributo y no está incrustado de forma fiable en ninguna de las cadenas. Clasificar errores por subclase de excepción más driver_error texto. Para la limitación de Azure SQL, véase lógica de intento.

Clasificación SQLSTATE

mssql-python utiliza el estado SQLSTATE devuelto por ODBC para elegir tanto la subclase de excepción de Python como el driver_error texto. El mapeo completo de SQLSTATE → excepciones está en exceptions.py el código fuente del driver. La siguiente sección enumera los SQLSTATEs que aparecen con mayor frecuencia con SQL Server y Azure SQL.

Errores de conexión

Fallos de conexión por mssql_python.connect() elevación mssql_python.OperationalError, igual que otros fallos de conectividad:

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"

Errores de cadena de conexión

Los errores de análisis de cadenas de conexión aumentan 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'

Referencia del código SQLSTATE

Los códigos SQLSTATE son códigos de cinco caracteres que identifican condiciones de error. Los dos primeros caracteres indican la clase, y los tres últimos indican la subclase. Rara vez necesitas inspeccionar estos códigos directamente. En su lugar, selecciona el tipo de excepción de Python apropiado (listado en la columna "Excepción"). Utiliza códigos SQLSTATE cuando necesites distinguir entre condiciones de error específicas dentro del mismo tipo de excepción, por ejemplo para diferenciar un bloqueo (40001) de un fallo general de conexión (08S01).

Clase 00 - Finalización exitosa

Clase 01 - Advertencia

Clase 07 - Error SQL dinámico

Clase 08 - Excepción de conexión

Clase 21 - Violación de cardinalidad

Clase 22 - Excepción de datos

Clase 23 - Violación de restricciones de integridad

Clase 24 - Estado del cursor inválido

Clase 25 - Estado de transacción inválido

Clase 28 - Especificación de autorización inválida

Clase 34 - Nombre de cursor inválido

Clase 3C - Nombre duplicado del cursor

Clase 3D - Nombre de catálogo inválido

Clase 3F - Nombre de esquema inválido

Clase 40 - Revertir transacciones

Clase 42 - Error de sintaxis o violación de la regla de acceso

Clase 44 - VIOLACIÓN DE LA OPCIÓN DE VERIFICACIÓN

Clase HY - Condición específica de CLI

Clase IM - Error del entrenador del piloto

Números de error comunes en SQL Server

Más allá de SQLSTATE, SQL Server proporciona números de error nativos entre paréntesis. Estos son los errores que es más probable que encuentres en el código de la aplicación. Construye la lógica de reintento alrededor del error 1205 (bloqueo) y errores de conexión transitoria (véase lógica de reintento).

Referencia rápida de síntoma a excepción

Utiliza esta tabla para mapear los síntomas comunes al tipo de excepción que deberías detectar:

procedimientos recomendados

• Detecta excepciones específicas antes que genéricas. Ordena de más específico (IntegrityError) a menos específico (Error).
• Siempre maneja IntegrityError para las operaciones de modificación de datos. Se esperan violaciones de restricciones en el funcionamiento normal (por ejemplo, un usuario que intenta crear un nombre de usuario duplicado).
• Registra el contexto completo del error para la resolución de problemas. La excepción expone driver_error (texto estable derivado de SQLSTATE) y ddbc_error (mensaje del lado del servidor). Registrar ambos; clasificar en driver_error.
• Implementa lógica de reintento para errores transitorios (fallos de conexión, bloqueos). Consulta lógica de reintento.
• Utiliza rollback() en los gestores de excepciones para limpiar transacciones fallidas. Sin una reversión explícita, la conexión permanece en estado de transacción fallida.

Contenido relacionado

• Guía de solución de problemas
• Ejecutar consultas
• Administración de conexiones