mssql-python 的错误处理与 SQLSTATE 代码

mssql-python 驱动定义了标准的异常层级结构、常见的错误处理模式以及针对 SQL Server 和 Azure SQL 的 SQLSTATE 代码映射。

异常层次结构

mssql-python驱动遵循 DB-API 2.0（PEP 249）异常层级结构：

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

ConnectionStringParseError (standalone, not part of hierarchy)

异常说明

抓住最符合你情况的具体例外。 例如，捕捉 IntegrityError / 操作上的INSERT约束违规，以及ProgrammingError开发过程中的 SQLUPDATE 语法问题。 基础 Error 职业只能作为备选。

基本错误处理

使用try-exclusion块来处理数据库错误：

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

通过连接的访问异常

你可以通过连接实例捕捉异常情况：

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

错误消息结构

MSSQL-Python 异常对象会暴露出来自驱动程序 Exception 基类的三个属性：

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

SQL Server 引擎的错误编号（例如 208 或 40501）不会作为属性暴露，也不会可靠地嵌入在任何字符串中。 通过例外子类加上 driver_error 文本来分类错误。 关于Azure SQL限速，请参见Retry logic。

SQLSTATE 分类

mssql-python 使用 ODBC 返回的 SQLSTATE 来选择 Python 异常子类和文本driver_error。 完整的 SQLSTATE →异常映射已在 exceptions.py 驱动源代码中。 下一节列出了SQL Server和Azure SQL中最常出现的SQLSTATE。

连接错误

来自 mssql_python.connect() 的 mssql_python.OperationalError连接失败与其他连接失败相同：

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"

连接字符串错误

连接字符串解析错误出现 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 代码参考

SQLSTATE 代码是五字符代码，用于识别错误状况。 前两个字符表示职业，后三个字符表示子职业。 你很少需要直接检查这些代码。 相反，要捕捉相应的 Python 异常类型（列在“异常”栏）。 当你需要区分同一例外类型内的特定错误条件时，可以使用SQLSTATE代码，例如区分死锁（40001）和一般连接故障（08S01）。

00级 - 成功完成

01级 - 警告

07类 - 动态SQL错误

08类 - 连接例外

第21类——基数违规

类别22 - 数据异常

第23类 - 完整性约束违规

类别24 - 无效光标状态

第25类 - 无效交易状态

第28类 - 无效授权规范

类别34 - 光标名称无效

3C 类 - 重复光标名称

3D类 - 目录名称无效

3F类 - 模式名称无效

40类 - 事务回滚

42类 - 语法错误或访问规则违规

44类——带有检查选项违规

HY类——CLI特异性疾病

类别 IM - 司机管理员错误

常见的SQL Server错误编号

除了 SQLSTATE，SQL Server 还在括号内提供原生错误编号。 这些是你在应用代码中最容易遇到的错误。 围绕错误1205（死锁）和瞬态连接错误（参见 重试逻辑）构建重试逻辑。

症状到异常快速引用

请使用此表将常见症状映射到你应捕捉的异常类型：

最佳做法

• 在处理泛泛的例外之前，先发现具体的例外情况。 按最具体的（IntegrityError）到最不具体Error的（）排序。
• 数据修改操作时务必处理IntegrityError 。 约束违规在正常操作中是预期的（例如，用户试图创建重复的用户名）。
• 记录完整的错误上下文 以便排查。 该例外暴露 driver_error （稳定文本，SQLSTATE派生文本）和 ddbc_error （服务器端消息）。 两者都记录;分类。driver_error
• 为瞬态错误（连接失败、死锁）实现重试逻辑。 参见 重试逻辑。
• 在例外处理程序中使用rollback（）来清理失败的事务。 如果没有显式回滚，连接会保持交易失败状态。

相关内容

• 故障排除指南
• 执行查询
• 连接管理