Skip to content

FEAT: Expose SQLSTATE on DB-API exceptions - #909

Open
Jahnvi Thakkar (jahnvi480) wants to merge 1 commit into
mainfrom
jahnvi/sqlstate-exception-attributes
Open

Jahnvi Thakkar (jahnvi480) wants to merge 1 commit into
mainfrom
jahnvi/sqlstate-exception-attributes

Conversation

@jahnvi480

Copy link
Copy Markdown
Contributor

Work Item / Issue Reference

N/A

GitHub Issue: #581


Summary

Expose optional sqlstate metadata on DB-API exceptions so callers can classify errors without matching English messages.

  • Preserve existing two-argument construction, exception classes, messages, and args; add an optional keyword-only sqlstate argument.
  • Retain SQLSTATE for mapped and unmapped synchronous ODBC errors, including connection failures. Use None when unavailable; async Rust/TDS errors retain that default.
  • Preserve metadata through pickle/copy operations and continue loading legacy pickle payloads.
  • Update public stubs, README guidance, and focused compatibility tests.

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.
  • Live SQL Server before/after comparison: missing-table SQLSTATE changes from unavailable to 42S02, with identical exception class, message, and args.

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>
Copilot AI balanced review requested due to automatic review settings November 20, 2026 04:11
@github-actions github-actions Bot added the pr-size: medium Moderate update size label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

PR Performance Report

✅ No regression detected

No 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 diagnostics

Phase 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 timings

Unix / SQL Server 2022

Database task Before After Paired change Result
Connection opening 10.342 ms 10.234 ms +1.2% no signal
SELECT queries 1.006 ms 1.035 ms +5.4% no signal
Row insertion 30.347 ms 30.364 ms +0.1% no signal
Executemany inserts 161.664 ms 160.238 ms -1.2% no signal
Fetch-all queries 119.298 ms 119.088 ms -0.7% no signal
Row-by-row fetching 4.932 ms 4.917 ms -0.4% no signal
Batched row fetching 115.249 ms 115.597 ms -0.0% no signal
Transaction commit and rollback 104.564 ms 107.284 ms +2.6% no signal
Arrow row fetching 88.298 ms 90.466 ms +2.3% no signal
100,000-row insertion 361.680 ms 343.420 ms -5.0% no signal
Row fetching in batches of 100 119.971 ms 120.523 ms +0.5% no signal
Row fetching in batches of 10,000 130.823 ms 138.819 ms +8.5% no signal
Repeated positional queries 31.808 ms 31.627 ms -0.6% no signal
Repeated named-parameter queries 32.085 ms 31.969 ms -0.7% no signal
Legacy 100,000-row insertion 255.994 ms 275.065 ms +6.5% no signal
Insertion with explicit input sizes 399.568 ms 385.652 ms +0.6% no signal
Joined aggregation queries 174.632 ms 180.877 ms +3.7% no signal
Large joined-result fetching 189.770 ms 191.931 ms +1.6% no signal
1.2-million-row fetching 3513.011 ms 3486.898 ms -0.7% no signal
Common table expression queries 5.178 ms 5.150 ms -0.2% no signal
256 KiB VARCHAR(MAX) / fetchall() 1.611 ms 1.575 ms -0.7% no signal
10,000 scalar values / fetchval() (debug disabled) 17.134 ms 16.870 ms -1.5% no signal
10,000 output-converted rows / fetchall() 19.693 ms 19.515 ms -2.2% no signal
10,000 output-converted rows / fetchmany(1000) 23.375 ms 23.954 ms +1.0% no signal
10,000 INT/NVARCHAR rows / fetchmany(1) 24.578 ms 25.240 ms +2.7% no signal
10,000 rows x 32 columns / dict(row._mapping) (warm) 32.032 ms 31.922 ms -0.3% no signal

Unix / SQL Server 2025

Database task Before After Paired change Result
Connection opening 81.749 ms 81.665 ms -0.0% no signal
SELECT queries 1.027 ms 1.124 ms +0.0% no signal
Row insertion 30.256 ms 30.525 ms +0.8% no signal
Executemany inserts 159.383 ms 159.815 ms +0.3% no signal
Fetch-all queries 123.819 ms 121.751 ms -1.5% no signal
Row-by-row fetching 4.989 ms 5.016 ms +0.6% no signal
Batched row fetching 118.122 ms 119.513 ms +1.7% no signal
Transaction commit and rollback 106.399 ms 106.891 ms +0.1% no signal
Arrow row fetching 90.230 ms 91.971 ms +1.9% no signal
100,000-row insertion 364.313 ms 362.493 ms +1.1% no signal
Row fetching in batches of 100 122.132 ms 121.946 ms +0.5% no signal
Row fetching in batches of 10,000 133.872 ms 145.694 ms +7.6% no signal
Repeated positional queries 32.603 ms 31.448 ms -3.5% no signal
Repeated named-parameter queries 32.072 ms 32.035 ms -1.3% no signal
Legacy 100,000-row insertion 260.867 ms 261.857 ms +3.4% no signal
Insertion with explicit input sizes 407.312 ms 392.488 ms -1.0% no signal
Joined aggregation queries 166.399 ms 163.138 ms -1.1% no signal
Large joined-result fetching 196.397 ms 193.691 ms -2.5% no signal
1.2-million-row fetching 3484.988 ms 3520.399 ms +0.5% no signal
Common table expression queries 5.160 ms 5.132 ms -0.5% no signal
256 KiB VARCHAR(MAX) / fetchall() 1.970 ms 2.036 ms +1.2% no signal
10,000 scalar values / fetchval() (debug disabled) 17.320 ms 17.534 ms -0.4% no signal
10,000 output-converted rows / fetchall() 20.156 ms 19.821 ms -0.7% no signal
10,000 output-converted rows / fetchmany(1000) 25.041 ms 24.952 ms -2.5% no signal
10,000 INT/NVARCHAR rows / fetchmany(1) 24.850 ms 24.752 ms +0.7% no signal
10,000 rows x 32 columns / dict(row._mapping) (warm) 32.067 ms 32.812 ms +1.8% no signal
Build and measurement details

ADO build 193887

PR head: 5e42bb6a24807c2e9642f311d25ed7aff7a49b43
Base: 52f30011b0b0229544cc50a8ef9f8ca0fb3d0e65
Measured merge: bde1c8af3419507794b0d842b6d06d634b5eba79

  • Unix / SQL Server 2022: Python 3.12.3, x86_64, SQL 16.0.4325.4; 5 paired comparisons and 1 warmup.
  • Unix / SQL Server 2025: Python 3.12.3, x86_64, SQL 17.0.5065.9; 5 paired comparisons and 1 warmup.

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 profiler-* artifacts.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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

@github-actions

Copy link
Copy Markdown

📊 Code Coverage Report

🔥 Diff Coverage

100%


🎯 Overall Coverage

86%


📈 Total Lines Covered: 11805 out of 13692
📁 Project: mssql-python


Diff Coverage

Diff: main...HEAD, staged and unstaged changes

  • mssql_python/exceptions.py (100%)

Summary

  • Total: 27 lines
  • Missing: 0 lines
  • Coverage: 100%

📋 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

⚙️ Build Summary 📋 Coverage Details

View Azure DevOps Build

Browse Full Coverage Report

@jahnvi480
Jahnvi Thakkar (jahnvi480) marked this pull request as ready for review November 20, 2026 08:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pr-size: medium Moderate update size

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants