Repository navigation
FEAT: Expose SQLSTATE on DB-API exceptions - #909
Jahnvi Thakkar (jahnvi480) wants to merge 1 commit into
Conversation
Preserve SQLSTATE metadata without changing existing exception messages, args, or legacy pickle reconstruction. Add public typing, documentation, and regression coverage. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
PR Performance Report✅ No regression detectedNo consistent slowdowns detected across all 2 environments. 0 IMPROVEMENTS 0 SLOWDOWNS 2/2 ENVIRONMENTS Coverage: 2 of 2 environments completed. Advisory result; does not block merging. Performance diagnosticsPhase times are inclusive diagnostics and must not be added together. They identify where measured time changed, not why it changed. No affected phases or call-count changes were recorded. All database tasks and timingsUnix / SQL Server 2022
Unix / SQL Server 2025
Build and measurement detailsPR head:
A consistent change requires more than 20% median paired movement, at least 1 ms between the median runtimes, and at least 80% of pairs exceeding the relative threshold in the same direction. A slowdown without enough pair agreement is reported as inconsistent. The displayed change is the median of paired before-and-after ratios. It is not recalculated from the two displayed median runtimes. Both revisions use profiling-enabled builds on the same agent and database, with alternating order and discarded warmups. Results are diagnostic and do not represent production-wheel latency. Raw samples and logs are attached to the ADO run as |
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain for the optional SQLSTATE metadata changes.
No open issues 🎉
What changed in this PR
Adds optional SQLSTATE metadata to the driver’s DB-API exceptions, addressing the SQLSTATE portion of #581 so callers can classify errors without parsing English messages. Native SQL Server error numbers remain deferred.
Changes:
- Preserve SQLSTATE for mapped and unmapped synchronous ODBC errors, including connection failures, without changing existing messages or
args. - Preserve metadata through pickle and copy operations while supporting legacy pickle payloads.
- Update public type stubs, usage guidance, and compatibility tests; async errors continue to default to
None.
| File | Description |
|---|---|
tests/test_typing.py |
Checks legacy and SQLSTATE-aware exception call shapes across public imports. |
tests/test_006_exceptions.py |
Covers SQLSTATE propagation, constructor compatibility, serialization, and copying. |
tests/AsyncTest/test_003_async_exceptions.py |
Verifies translated async errors default to no SQLSTATE. |
README.md |
Documents SQLSTATE-based classification and its limitations. |
mssql_python/mssql_python.pyi |
Adds SQLSTATE constructor parameters and attribute types. |
mssql_python/exceptions.py |
Stores, propagates, and serializes optional SQLSTATE metadata. |
mssql_python/connection.py |
Retains SQLSTATE in the unmapped connection-error fallback. |
Review effort: Balanced
📊 Code Coverage Report
Diff CoverageDiff: main...HEAD, staged and unstaged changes
Summary
📋 Files Needing Attention📉 Files with overall lowest coverage (click to expand)mssql_python.pybind.performance_counter.hpp: 0.7%
mssql_python.pybind.logger_bridge.cpp: 57.9%
mssql_python.pybind.ddbc_bindings.h: 64.5%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python._native_fetch.py: 77.7%
mssql_python.pybind.ddbc_bindings.cpp: 81.4%
mssql_python.pybind.row_mapping_cache.hpp: 81.5%
mssql_python.pybind.connection.connection_pool.cpp: 82.5%
mssql_python.pybind.connection.connection.cpp: 83.1%
mssql_python.logging.py: 86.8%🔗 Quick Links
|
Work Item / Issue Reference
Summary
Expose optional
sqlstatemetadata on DB-API exceptions so callers can classify errors without matching English messages.args; add an optional keyword-onlysqlstateargument.Nonewhen unavailable; async Rust/TDS errors retain that default.Native SQL Server error numbers remain explicitly deferred; this PR does not complete that portion of the linked issue or change retry behavior.
Validation (project Python 3.13 development environment; native extension built successfully):
python -m pytest tests\test_006_exceptions.py tests\test_027_retry_policy.py tests\AsyncTest\test_003_async_exceptions.py -q --tb=short— 210 passed, 1 xfailed.python -m pytest tests\test_typing.py -m typing -q --tb=short— 7 passed.python -m pre_commit run black-check --all-files --hook-stage pre-push— passed.python -m pytest -q --tb=short— 6932 passed, 188 skipped, 49 deselected, 1 xfailed, 2 failed. Both failures also reproduce with baseline production modules: the password-masking logging assertion and Windows long-path test.42S02, with identical exception class, message, andargs.