Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

FEAT: Expose SQLSTATE (and native error number) as attributes on exception objects

Đang mở
  • Có gì không ổn?
#581 1 bình luận 1 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@gargsaumya đang làm issue này rồi.

Từ ngày 15/5/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

area: api-compliance triage needed

Summary

mssql_python discards the SQLSTATE code after using it to choose an exception subclass, so callers cannot programmatically classify errors by SQLSTATE. The only stable hook left is substring-matching the English driver_error text, which is brittle and forces every consumer to duplicate the driver's internal SQLSTATE → text table.

Please expose SQLSTATE as a public attribute on the exception (and ideally also the native SQL Server error number).

Why this matters

SQLSTATE is the one stable, standardized, locale-independent error identifier in ODBC. It's exactly what application code needs to decide things like:

  • Is this transient? Retry it. (e.g. HYT00, 08S01, 40001)
  • Is this a deadlock specifically vs. some other operational error? (40001)
  • Is this an Azure SQL throttling response? (engine 40501 under 42000)
  • Is this an auth failure that means "refresh the access token"? (28000)

Today none of that is possible without one of two bad options:

  1. Substring-match driver_error against a frozenset of English phrases copied out of exceptions.py. This pins user code to internal driver constants, breaks if the strings are ever reworded or localized, and forces every consumer to maintain their own copy of the SQLSTATE-to-phrase mapping.
  2. Regex-scrape ddbc_error for Error NNNN to recover the SQL Server engine number. Fragile and explicitly not a stable contract.

Compare to peer drivers:

Driver Stable error identifier
pyodbc exc.args[0] is the 5-char SQLSTATE
pymssql exc.args[0] is the SQL Server engine error number
mssql-python Neither; SQLSTATE is consumed and discarded in sqlstate_to_exception()

PEP 249 doesn't standardize this, but every mature driver exposes something. mssql-python is currently the odd one out.

Proposed change

In mssql_python/exceptions.py:

  1. Add sqlstate (and optionally native_error) as keyword args to Exception.__init__ and store them on self.
  2. Update sqlstate_to_exception(sqlstate, ddbc_error) to pass sqlstate=sqlstate into every constructor call (it already has the value in hand).
  3. Update the DatabaseError fallback in raise_exception() to pass the SQLSTATE through as well.

Roughly:

class Exception(builtins.Exception):
    def __init__(self, driver_error: str, ddbc_error: str,
                 sqlstate: Optional[str] = None,
                 native_error: Optional[int] = None) -> None:
        self.driver_error = driver_error
        self.ddbc_error = truncate_error_message(ddbc_error)
        self.sqlstate = sqlstate
        self.native_error = native_error
        ...

This is fully backward compatible: existing callers that only read driver_error / ddbc_error / str(exc) keep working unchanged.

How callers would use it

TRANSIENT_SQLSTATES = frozenset({
    "HYT00", "HYT01",   # Timeouts
    "08001", "08S01", "08007",  # Connection failures
    "40001", "40003",   # Deadlock / indeterminate completion
})

def is_transient(exc: BaseException) -> bool:
    return getattr(exc, "sqlstate", None) in TRANSIENT_SQLSTATES

This is what retry-logic samples in the official SQL Server docs would prefer to show, instead of the current English-text frozenset.

Related

PR #562 (fix for #532) is already plumbing SQLSTATE through Connection::checkError() into sqlstate_to_exception(). The value is now reaching the exception constructor from both the cursor path and the connection path. Exposing it on self is the natural next step and is essentially free once #562 lands.

Environment

  • mssql-python 1.5.0
  • Verified empirically: dir(exc) on OperationalError, ProgrammingError, DataError shows no sqlstate, native_error, errno, or code attribute.
Ngôn ngữ chính
Python
Star
478
Fork
62
Merge trung bình
3 ngày 1 giờ
Pull request đã merge (30 ngày)
27

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của microsoft/mssql-python

Tất cả issue của microsoft/mssql-python

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.