ODBC connection pooling (ADO #47317)

[Saurabh Singh (saurabh500)]

Implements Connection Pool constructs in mssql-odbc for ADO User Story #47317, so mssql-python's client-side connection pool can safely reuse a physical Rust ODBC connection across borrowers.

This is the single, consolidated PR for the feature (the earlier stacked stage PRs #293/#294/#296/#301/#302 have been closed in favor of this one). All four stages' work is included here against main.

What this delivers

• mssql-tds reset correctness (AB#47337). All ResetConnection ENVCHANGE sites route through TdsClient::on_reset_connection_ack(), which resets the session-state table, clears session-bound caches (prepared handles, param-encryption, pending captures) via clear_session_bound_caches(), and restores negotiated DATABASE/LANGUAGE/COLLATION to login values. Fatal error tokens (severity >= 20) mark the transport dead via mark_known_dead() so a poisoned connection is discarded by the pool.
• ODBC pooling primitives (AB#47338). SQL_ATTR_CONNECTION_DEAD (cached, never-probe liveness read, DEAD-until-proven) and the pooling reset attribute (value validation → HY024; 08003 when disconnected; busy rejection via claim-idle; rollback of a live local txn; arm the reset bit). The reset is accepted under both spellings — the ODBC 3.8 SQL_ATTR_RESET_CONNECTION (116) and the msodbcsql vendor attribute SQL_COPT_SS_RESET_CONNECTION (1246) — so both the direct-loading mssql-python consumer and Driver-Manager-mediated callers can request a check-in reset (see below).
• Self-acking reset at checkout (AB#47339). TdsClient::reset_connection() arms RESETCONNECTION and drives a round trip that forces the ENVCHANGE ack (clearing session-bound caches); on failure the client is poisoned and 08S01 is surfaced so mssql-python discards it. The SQL_ATTR_TXN_ISOLATION handler emits a real SET TRANSACTION ISOLATION LEVEL batch, because sp_reset_connection does not reset isolation (D9) — matching mssql-python PR #343, which re-applies READ COMMITTED on every checkout.
• Auth-reuse confirmation, tests, and docs (AB#47340). Confirmed a reset reuses the same physical login (no re-auth; a rotated token post-connect is rejected), with a unit test. C++ live e2e connection_pool_test.cpp covers same-SPID reuse, clean state for the next borrower, per-checkout isolation reset, connection-liveness, and prepared-statement behavior across reset. Shared behavior is verified on both drivers; the one intended mssql-odbc-specific divergence (transparent re-prepare of a dropped handle, which msodbcsql fails with native 8179) is isolated behind SKIP_IF_COMPARING_MSODBCSQL().

Design doc

• docs/odbc-connection-pooling-plan.md — full design: consumer analysis, discoveries D1–D10, workstreams, DoD, and non-goals.
• docs/odbc-connection-pooling-python-e2e.md — mssql-python pool integration verification plan (scenarios a–f) via the existing run_e2e.ps1/run_e2e.sh driver-registration hook.

Work items

Fixes AB#47317. Implements AB#47337, AB#47338, AB#47339, AB#47340.

Why the reset attribute is accepted under two identifiers (D10)

SQL_ATTR_RESET_CONNECTION (116) is an ODBC 3.8 attribute reserved for Driver Manager → driver communication: the DM sets it itself when returning a connection to its own pool, and per the 3.8 driver guidance "an application cannot set this attribute directly." The Windows DM enforces that — a DM-mediated application that sets it gets HY092 ("Option type out of range") from the DM before the call reaches any driver. This is not driver-specific: the installed msodbcsql18 fails identically. Such callers use msodbcsql's vendor attribute SQL_COPT_SS_RESET_CONNECTION (SQL_COPT_SS_BASE_EX+6 = 1246, value SQL_RESET_YES, odbcss.h) instead, since vendor-range attributes are passed straight through. unixODBC applies no such gate, so 116 reaches the driver on Linux/macOS.

mssql-python — the consumer this feature exists for — is not subject to that gate, because it does not use a Driver Manager. It loads the driver library directly (LoadDriverLibrary() in mssql_python/pybind/ddbc_bindings.cpp: LoadLibraryW on Windows, dlopen elsewhere), binds the exports via GetProcAddress/dlsym (SQLSetConnectAttr_ptr et al.), and calls them itself. Its SQL_ATTR_RESET_CONNECTION = 116 therefore arrives at our exported SQLSetConnectAttrW unchanged on every platform, Windows included — no upstream change is required.

So the driver handles both identifiers on every platform: 116 for the direct-loading consumer, and 1246 for DM-mediated callers on Windows — which includes this repo's own C++ e2e suite, since it links against the Driver Manager. connection_pool_test.cpp selects the spelling its transport requires and passes against both mssql-odbc and msodbcsql.

An earlier commit in this PR attempted to fix the Windows e2e HY092 by advertising DriverODBCVer = "03.80" in the test registry registration. That was the wrong diagnosis — the DM's rejection is about who may set attribute 116, not about the driver's advertised ODBC version — and it did not fix the failure. That change has been reverted; no DriverODBCVer change is needed, and this imposes no new requirement on a real install of the driver.

Notes

Draft. Merge is author-owned.

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 97%

🎯 Overall Coverage 91.6%

📦 Project: mssql-tds + mssql-odbc + mssql-py-core ℹ️ Note: diff coverage is reported, not enforced.

---

Diff Coverage

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

• mssql-odbc/src/api/get_connect_attr.rs (100%)
• mssql-odbc/src/api/set_connect_attr.rs (100%)
• mssql-odbc/src/api/txn.rs (94.7%): Missing lines 382-383,414-415,419-421,439-440
• mssql-tds/src/connection/tds_client.rs (98.5%): Missing lines 1321,4064
• mssql-tds/src/connection/transport/tds_transport.rs (0.0%): Missing lines 93
• mssql-tds/src/test_client_support.rs (100%)

Summary

• Total: 417 lines
• Missing: 12 lines
• Coverage: 97%

mssql-odbc/src/api/txn.rs

  378     const OP: &str = "SQLSetConnectAttrW(SQL_ATTR_RESET_CONNECTION)";
  379 
  380     {
  381         let Ok(mut state) = dbc.inner.lock() else {
! 382             error!("{OP}: dbc mutex poisoned");
! 383             return SQL_ERROR;
  384         };
  385         free_errors(&mut state);
  386         if value != u64::from(SQL_RESET_CONNECTION_YES) {
  387             error!(value, "{OP}: invalid value");

---

  410             // A poisoned mutex leaves the transaction flag unreadable, so a
  411             // required rollback could be skipped. Fail deterministically like
  412             // every other DBC lock site rather than resetting on a DBC whose
  413             // state is already compromised.
! 414             error!("{OP}: dbc mutex poisoned");
! 415             return SQL_ERROR;
  416         }
  417     };
  418     let result = if started && client.has_active_transaction() {
! 419         debug!("{OP}: rolling back live local transaction before reset");
! 420         dbc.runtime
! 421             .block_on(client.rollback_transaction(None, None))
  422     } else {
  423         Ok(())
  424     };

---

  435     }
  436     release_dbc_client(dbc, client);
  437 
  438     let Ok(mut state) = dbc.inner.lock() else {
! 439         error!("{OP}: dbc mutex poisoned");
! 440         return SQL_ERROR;
  441     };
  442     state.local_tran_started = false;
  443     if let Err(e) = result {
  444         error!(%e, "{OP}: connection reset failed");

---

mssql-tds/src/connection/tds_client.rs

  1317                 }
  1318                 Tokens::EnvChange(env_change) => {
  1319                     info!(?env_change);
  1320                     if env_change.sub_type == EnvChangeTokenSubType::ResetConnection {
! 1321                         self.on_reset_connection_ack();
  1322                     }
  1323                     self.execution_context
  1324                         .capture_change_property(&env_change, &mut self.negotiated_settings)?;
  1325                     continue;

---

  4060             }
  4061             Tokens::EnvChange(env_change) => {
  4062                 info!(?env_change);
  4063                 if env_change.sub_type == EnvChangeTokenSubType::ResetConnection {
! 4064                     self.on_reset_connection_ack();
  4065                 }
  4066                 self.execution_context
  4067                     .capture_change_property(&env_change, &mut self.negotiated_settings)?;
  4068                 Ok(None)

---

mssql-tds/src/connection/transport/tds_transport.rs

  89     /// has not seen a socket-level failure, so a later pool checkout must
  90     /// discard the connection.
  91     ///
  92     /// [`connection_known_dead`]: TdsTransport::connection_known_dead
! 93     fn mark_known_dead(&mut self) {}
  94 }

---

---

🔗 Quick Links

View Azure DevOps Build · Coverage Report

[Copilot]

Pull request overview

Adds TDS and ODBC primitives required for safe physical-connection reuse by mssql-python’s client-side pool.

Changes:

• Centralizes TDS reset acknowledgement and fatal-error liveness handling.
• Adds ODBC reset, connection-dead, and isolation behavior.
• Adds unit, live E2E, and integration-verification coverage.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
mssql-tds/tests/test_reset_connection.rs	Tests prepared-handle invalidation.
mssql-tds/src/test_client_support.rs	Adds reset and liveness test support.
mssql-tds/src/connection/transport/tds_transport.rs	Adds transport death marking.
mssql-tds/src/connection/transport/network_transport.rs	Implements death marking.
mssql-tds/src/connection/tds_client.rs	Handles reset acknowledgements and fatal errors.
mssql-tds/src/connection/execution_context.rs	Delegates reset state handling.
mssql-odbc/tests/e2e/tests/connection_pool_test.cpp	Adds live pooling tests.
mssql-odbc/tests/e2e/run_e2e.ps1	Removes formatting noise.
mssql-odbc/tests/e2e/CMakeLists.txt	Registers pooling tests.
mssql-odbc/src/api/txn.rs	Implements eager reset and isolation flow.
mssql-odbc/src/api/sqlstate.rs	Adds communication-failure SQLSTATE.
mssql-odbc/src/api/set_connect_attr.rs	Routes reset attributes.
mssql-odbc/src/api/odbc_types.rs	Defines pooling constants.
mssql-odbc/src/api/get_connect_attr.rs	Reports cached connection liveness.
docs/odbc-connection-pooling-python-e2e.md	Documents Python integration verification.
docs/odbc-connection-pooling-plan.md	Describes pooling design and delivery plan.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.