tds/odbc: unified execute + statement-wise result navigation API (msodbcsql parity)

[David-Engel]

Summary

Replaces the split execute/result-navigation surface in mssql-tds with a single unified API, and makes statement-wise result navigation (msodbcsql parity) the default across every consumer.

This started (superseding #141) as additive statement-wise SQLMoreResults navigation for mssql-odbc. In review we decided that, since these APIs have no external consumers to preserve, a clean breaking redesign is better than carrying two parallel navigation paths forever. This PR now delivers that unified API and migrates all consumers plus the full test suite.

New unified API (mssql-tds)

• execute(sql, options) -> StatementResult, where options: impl Into<ExecuteOptions> so () selects defaults.
• StatementResult: Rows / NoRows { rows_affected } / End.
• advance() -> StatementResult — drain the current statement and move to the next statement boundary.
• advance_to_rows() -> bool — collapse forward to the next row-returning statement (preserves the old collapsing behavior where a caller wants it).
• on_rows() and has_open_batch() accessors.
• ExecuteOptions { timeout, cancel, column_encryption } (with Default + builder methods) replaces the trailing timeout, cancel (and encryption-setting) parameters on every execute_* method.

msodbcsql rule (verified by probing the reference driver): a statement is a navigable result iff it returns rows, carries a row count (DONE COUNT flag), or produced messages (INFO). Pure no-op statements (e.g. a bare CREATE TABLE) collapse. Predicate: has_count || saw_message.

Breaking changes

Removed in favor of the unified surface:

• execute_multi_statement, move_to_next_statement
• the ResultSetClient trait (get_current_resultset / move_to_next)
• execute_sp_executesql_with_encryption_setting / _core
• the expose_norow bool on the result-boundary loop — statement-wise navigation is now unconditional.

Every execute_* method now takes impl Into<ExecuteOptions> instead of positional timeout / cancel args.

Consumers migrated

mssql-odbc, mssql-js, mssql-py-core, mssql-tds-cli, and mssql-tds-bench, plus the full mssql-tds unit + integration test suite (~40 files).

Production fix

get_next_row_into's error arm now clears has_open_batch / result-set state after draining, so close_query / advance no longer hang after a mid-row server error.

New test scaffolding: mssql-tds/src/test_client_support.rs

This PR adds a small test-util-gated module that builds a TdsClient on top of a mock transport which replays a scripted sequence of TDS tokens (COLMETADATA, DONE/DONEPROC with specific flags, INFO) instead of talking to a live server. It is not shipped API and is excluded from coverage reporting.

Why it's needed. The unified statement-wise navigation pushes real logic into the seam between the TDS layer and the ODBC layer — no-row results, message-only statements, end-of-batch, and the defensive error guards. Several of those paths are impossible or flaky to reach through a real server:

• Internal error guards can't be produced by a real server — e.g. an ODBC statement left cursor-open while its connection has no active client, or a transport that dies mid-drain.
• Some token shapes are awkward to coax out of SQL Server — e.g. a zero-column COLMETADATA, or an exact DONE flag combination such as MORE|COUNT.
• These are unit tests: they run in the Build stage with no SQL host, and they assert on driver-internal state (STMT/DBC handle state, SQLSTATEs, cursor open/closed) that the black-box ODBC C API does not expose.

Benefits.

• Deterministic, hermetic coverage of the ODBC result-navigation state machine and its error branches — no server, no network flakiness.
• Fast feedback in the Build stage, complementing the live integration tests and the e2e --compare-with-msodbcsql parity run, which cover the happy paths end-to-end.

Why it lives in mssql-tds behind a feature. Constructing a positioned TdsClient requires crate-internal transport traits (TdsTransport, TdsTokenStreamReader, …) and TdsClient::new. Exposing these helpers through the test-util feature — opted into by mssql-odbc's dev-dependency — is the idiomatic Rust pattern; a separate testkit crate would instead force widening many internals to pub.

Tests & parity

• Whole workspace builds; clippy + fmt clean.
• mssql-tds lib + integration suites, mssql-odbc lib, and the mock / cursor / rpc / tvp / reset-connection / bulk-copy suites are green (local SQL Server 2022; VECTOR and a timing-flaky table-lock case aside, which are environment/flake, not regressions).
• e2e run_e2e.sh --compare-with-msodbcsql: 14 parity / 0 bugs. The comparison caught one real regression — prepared DML left a 0-column cursor open (SQLSTATE 24000 on reuse) — fixed by draining non-Rows prepared results to idle in the SQLExecute path.

[Copilot]

Pull request overview

Adds statement-wise result navigation for ODBC parity while preserving existing result-set behavior for other consumers.

Changes:

• Adds StatementResult-based TDS navigation.
• Maps no-row results through ODBC execution, fetch, and SQLMoreResults.
• Updates parity-focused end-to-end tests.

Reviewed changes

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

Show a summary per file

File	Description
mssql-tds/src/connection/tds_client.rs	Implements statement-boundary navigation and tests.
mssql-odbc/src/api/exec_direct.rs	Enables navigation for plain batches.
mssql-odbc/src/api/exec_common.rs	Preserves pending no-row results.
mssql-odbc/src/api/more_results.rs	Maps statement results to ODBC returns.
mssql-odbc/src/api/fetch.rs	Rejects fetches from zero-column results.
mssql-odbc/tests/e2e/tests/exec_direct_test.cpp	Tests separate informational statements.
mssql-odbc/tests/e2e/tests/more_results_test.cpp	Tests navigation through PRINT results.

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 83%

🎯 Overall Coverage 90.3%

📦 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/exec_common.rs (70.6%): Missing lines 177,272-274,287
• mssql-odbc/src/api/exec_direct.rs (95.8%): Missing lines 132-133
• mssql-odbc/src/api/execute.rs (0.0%): Missing lines 70,75-80,91-96,99-103,114-115,117-118
• mssql-odbc/src/api/fetch.rs (85.7%): Missing lines 112-116,130
• mssql-odbc/src/api/free_handle.rs (0.0%): Missing lines 238
• mssql-odbc/src/api/more_results.rs (93.9%): Missing lines 131-135,150
• mssql-py-core/src/cursor.rs (88.0%): Missing lines 88-89,93
• mssql-tds/src/connection/cursor_ops.rs (100%)
• mssql-tds/src/connection/tds_client.rs (91.7%): Missing lines 1919,1921,2973,3474-3475,3479-3482,3485-3488,3491-3494
• mssql-tds/src/test_client_support.rs (70.4%): Missing lines 98,100,108,110,115,117-118,120,131-136,144,147-150,159-162,164-165,167-170

Summary

• Total: 557 lines
• Missing: 91 lines
• Coverage: 83%

mssql-odbc/src/api/exec_common.rs

  173         return;
  174     };
  175     if let Err(e) = dbc
  176         .runtime
! 177         .block_on(client.execute_sp_unprepare(handle, ()))
  178     {
  179         error!(%e, handle, "{op}: sp_unprepare failed — handle leaked until disconnect");
  180     }
  181 }

---

  268         // 24000). Do NOT drain the wire — that would collapse the rest of the
  269         // batch. Matches msodbcsql.
  270         let info_messages = client.take_info_messages();
  271         let Ok(mut stmt_state) = stmt.inner.lock() else {
! 272             error!("{op}: stmt mutex poisoned on no-row result");
! 273             return_client_busy(dbc, client);
! 274             return SQL_ERROR;
  275         };
  276         stmt_state.column_metadata = metadata; // empty (0 columns)
  277         stmt_state.set_state(STMT_STATE_EXEC_CONTEXT | STMT_STATE_CURSOR_OPEN);
  278         stmt_state.clear_state(STMT_STATE_EXEC_STARTED);

---

  283             SQL_SUCCESS_WITH_INFO
  284         } else {
  285             SQL_SUCCESS
  286         };
! 287     }
  288 
  289     if !has_result_set {
  290         // DDL / DML (last / only statement): drain trailing DONE tokens and
  291         // return to idle so the statement can re-execute without an explicit

---

mssql-odbc/src/api/exec_direct.rs

  128     // handle); unparameterized text runs as a plain SQL batch. Neither DBC nor
  129     // STMT lock is held during I/O.
  130     let exec_result: Result<(), mssql_tds::error::Error> = if marker_count > 0 {
  131         dbc.runtime
! 132             .block_on(client.execute_sp_executesql(rewritten_sql, named_params, ()))
! 133             .map(|_| ())
  134     } else {
  135         // Statement-wise navigation: position on the batch's first statement
  136         // (msodbcsql parity) so no-row statements (PRINT / RAISERROR / DML) are
  137         // individually navigable via SQLMoreResults. finish_execute inspects the

---

mssql-odbc/src/api/execute.rs

  66         Ok(client) => client,
  67         Err(rc) => return rc,
  68     };
  69 
! 70     let exec_result = match exec.handle {
  71         // Already prepared: reuse the cached server handle (msodbcsql
  72         // `cmdp.hPrepCurrent`) via sp_execute. No pending prepared handle drop can
  73         // exist here. (StmtState invariant: `pending_unprepare` is set only when
  74         // `prepared_handle` is None), so nothing to release.
! 75         Some(handle) => dbc.runtime.block_on(client.execute_sp_execute(
! 76             handle,
! 77             None,
! 78             Some(exec.named_params),
! 79             (),
! 80         )),
  81         // First execute / re-prepare: prepare and run in one round trip via
  82         // sp_prepexec (deferred-prepare path). A prepared handle superseded
  83         // by a prior rebind / re-prepare is dropped in the same RPC by passing
  84         // it as sp_prepexec's `@handle` input (`drop_handle`). This avoids

---

   87         // NOTE: msodbcsql falls back to sp_prepare + sp_execute for statements
   88         // with data-at-execution (DAE) parameters, which sp_prepexec can't
   89         // carry. Phase 1 rejects DAE params at bind time, so that case can't
   90         // occur here yet - add the sp_prepare branch when DAE support lands.
!  91         None => dbc.runtime.block_on(client.execute_sp_prepexec(
!  92             exec.rewritten_sql,
!  93             exec.named_params,
!  94             exec.drop_handle,
!  95             (),
!  96         )),
   97     };
   98 
!  99     let stmt_result = match exec_result {
! 100         Ok(result) => result,
! 101         Err(e) => {
! 102             error!(%e, "SQLExecute: prepared execution failed");
! 103             return fail_with_tds(dbc, stmt, statement_handle, client, &e);
  104         }
  105     };
  106 
  107     // A prepared statement runs a single SQL statement. If it produced no result

---

  110     // 0-column cursor open — matching how the pre-statement-wise path collapsed
  111     // no-row results. A row-returning statement keeps its cursor open for
  112     // SQLFetch; its `@handle` RETURNVALUE (sp_prepexec) is captured later at
  113     // drain time (SQLCloseCursor / the DDL finish path).
! 114     if !matches!(stmt_result, StatementResult::Rows)
! 115         && let Err(e) = dbc.runtime.block_on(client.advance_to_rows())
  116     {
! 117         error!(%e, "SQLExecute: draining no-row prepared result failed");
! 118         return fail_with_tds(dbc, stmt, statement_handle, client, &e);
  119     }
  120 
  121     finish_execute(dbc, stmt, statement_handle, client, "SQLExecute")
  122 }

---

mssql-odbc/src/api/fetch.rs

  108     {
  109         let no_columns = match stmt.inner.lock() {
  110             Ok(ss) => ss.column_metadata.is_empty(),
  111             Err(_) => {
! 112                 error!("SQLFetch: stmt mutex poisoned checking no-row result");
! 113                 if let Ok(mut ds) = dbc.inner.lock() {
! 114                     ds.client = Some(client);
! 115                 }
! 116                 return SQL_ERROR;
  117             }
  118         };
  119         if no_columns {
  120             error!("SQLFetch: current result has no columns (no-row statement)");

---

  126             if let Ok(mut ss) = stmt.inner.lock() {
  127                 post_diag(&mut ss, ERR_INVALID_CURSOR_STATE);
  128             }
  129             return SQL_ERROR;
! 130         }
  131     }
  132 
  133     let fetch_result = dbc.runtime.block_on(client.next_row());

---

mssql-odbc/src/api/free_handle.rs

  234 
  235     for handle in handles {
  236         if let Err(e) = dbc
  237             .runtime
! 238             .block_on(client.execute_sp_unprepare(handle, ()))
  239         {
  240             error!(%e, handle, "SQLFreeHandle(STMT): sp_unprepare failed — handle leaked until disconnect");
  241         }
  242     }

---

mssql-odbc/src/api/more_results.rs

  127             // (SQLFetch returns 24000), but it is a navigable result and may
  128             // carry diagnostic messages. The connection stays busy so a further
  129             // SQLMoreResults can advance past it. Matches msodbcsql.
  130             let Ok(mut stmt_state) = stmt.inner.lock() else {
! 131                 error!("SQLMoreResults: stmt mutex poisoned on no-row result");
! 132                 if let Ok(mut ds) = dbc.inner.lock() {
! 133                     ds.client = Some(client);
! 134                 }
! 135                 return SQL_ERROR;
  136             };
  137             stmt_state.column_metadata.clear();
  138             stmt_state.current_row = None;
  139             let info_messages = client.take_info_messages();

---

  146             debug!("SQLMoreResults: advanced to a no-row statement result");
  147             if has_server_info {
  148                 SQL_SUCCESS_WITH_INFO
  149             } else {
! 150                 SQL_SUCCESS
  151             }
  152         }
  153         Ok(StatementResult::End) => {
  154             // Batch exhausted. Close cursor state and release the connection.

---

mssql-py-core/src/cursor.rs

  84                 // row-returning result set, so collapse forward to it — matching
  85                 // the pre-statement-wise behavior fetchone/fetchall expect.
  86                 if !matches!(first, StatementResult::Rows) {
  87                     client.advance_to_rows().await.map_err(|e| {
! 88                         error!("execute: Failed to advance to first result set: {}", e);
! 89                         pyo3::exceptions::PyRuntimeError::new_err(format!(
  90                             "Query execution failed: {}",
  91                             e
  92                         ))
! 93                     })?;
  94                 }
  95 
  96                 info!("execute: Query executed successfully");
  97                 Ok::<_, PyErr>(())

---

mssql-tds/src/connection/tds_client.rs

  1915                 Tokens::TabName | Tokens::ColInfo => {
  1916                     continue;
  1917                 }
  1918                 _ => {
! 1919                     info!("advance_to_result_boundary: {:?}", token);
  1920                     return Err(UsageError(format!(
! 1921                         "Unexpected token while moving to next result boundary: {token:?}"
  1922                     )));
  1923                 }
  1924             }
  1925         }

---

  2969             }
  2970             Tokens::ColMetadata(_) => Err(crate::error::Error::UsageError(
  2971                 "Unexpected ColMetadata token encountered while reading rows. \
  2972                      This typically indicates the API was not used correctly - \
! 2973                      you may need to call advance_to_rows() to advance to the next result set."
  2974                     .to_string(),
  2975             )),
  2976             Tokens::Info(info_token) => {
  2977                 info!(?info_token);

---

  3470 }
  3471 
  3472 impl<'a> ExecuteOptions<'a> {
  3473     /// Creates default options (inherit all connection behavior).
! 3474     pub fn new() -> Self {
! 3475         Self::default()
  3476     }
  3477 
  3478     /// Sets a per-request timeout, in seconds.
! 3479     pub fn timeout_secs(mut self, seconds: u32) -> Self {
! 3480         self.timeout = Some(seconds);
! 3481         self
! 3482     }
  3483 
  3484     /// Attaches a cancellation handle.
! 3485     pub fn cancel(mut self, handle: &'a CancelHandle) -> Self {
! 3486         self.cancel = Some(handle);
! 3487         self
! 3488     }
  3489 
  3490     /// Overrides the Always Encrypted behavior for this command only.
! 3491     pub fn column_encryption(mut self, setting: ExecutionColumnEncryptionSetting) -> Self {
! 3492         self.column_encryption = setting;
! 3493         self
! 3494     }
  3495 }
  3496 
  3497 impl From<()> for ExecuteOptions<'_> {
  3498     fn from(_: ()) -> Self {

---

mssql-tds/src/test_client_support.rs

   94         _pause_state: RowPauseState,
   95         _remaining_request_timeout: Option<Duration>,
   96         _cancel_handle: Option<&CancelHandle>,
   97         _writer: &mut (dyn RowWriter + Send),
!  98     ) -> TdsResult<RowReadResult> {
   99         Err(crate::error::Error::ConnectionClosed("test".to_string()))
! 100     }
  101 
  102     async fn read_active_plp_bytes(
  103         &mut self,
  104         _plp_state: &mut PlpPauseState,

---

  104         _plp_state: &mut PlpPauseState,
  105         _remaining_request_timeout: Option<Duration>,
  106         _cancel_handle: Option<&CancelHandle>,
  107         _out: &mut [u8],
! 108     ) -> TdsResult<usize> {
  109         Err(crate::error::Error::ConnectionClosed("test".to_string()))
! 110     }
  111 }
  112 
  113 #[async_trait]
  114 impl TransportSslHandler for TokenReplayTransport {
! 115     async fn enable_ssl(&mut self) -> TdsResult<()> {
  116         Ok(())
! 117     }
! 118     async fn disable_ssl(&mut self) -> TdsResult<()> {
  119         Ok(())
! 120     }
  121 }
  122 
  123 #[async_trait]
  124 impl NetworkWriter for TokenReplayTransport {

---

  127     }
  128     fn packet_size(&self) -> u32 {
  129         4096
  130     }
! 131     fn get_encryption_setting(&self) -> NegotiatedEncryptionSetting {
! 132         NegotiatedEncryptionSetting::NoEncryption
! 133     }
! 134     fn set_reset_mode(&mut self, mode: ResetConnectionMode) {
! 135         self.reset_mode = mode;
! 136     }
  137     fn take_reset_mode(&mut self) -> ResetConnectionMode {
  138         std::mem::replace(&mut self.reset_mode, ResetConnectionMode::None)
  139     }
  140 }

---

  140 }
  141 
  142 #[async_trait]
  143 impl NetworkReader for TokenReplayTransport {
! 144     async fn receive(&mut self, buffer: &mut [u8]) -> TdsResult<usize> {
  145         buffer.fill(0);
  146         Ok(0)
! 147     }
! 148     fn packet_size(&self) -> u32 {
! 149         4096
! 150     }
  151 }
  152 
  153 #[async_trait]
  154 impl TdsTransport for TokenReplayTransport {

---

  155     fn as_writer(&mut self) -> &mut dyn NetworkWriter {
  156         self
  157     }
  158     fn reset_reader(&mut self) {}
! 159     fn packet_size(&self) -> u32 {
! 160         4096
! 161     }
! 162     async fn close_transport(&mut self) -> TdsResult<()> {
  163         Ok(())
! 164     }
! 165     async fn send_attention_with_timeout(&mut self, _timeout: Duration) -> TdsResult<bool> {
  166         Ok(false)
! 167     }
! 168     fn is_connection_dead(&self) -> bool {
! 169         true
! 170     }
  171 }
  172 
  173 /// Builds a [`TdsClient`] whose transport replays `tokens`. Combine with the
  174 /// public statement-wise navigation API

---

---

🔗 Quick Links

View Azure DevOps Build · Coverage Report

[Copilot]

Pull request overview

Copilot reviewed 66 out of 66 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

mssql-js/src/connection.rs:157

• A procedure that first emits a row count is now left on NoRows. The unchanged createResultFast() stops when its first fetchChunk() returns None, so it neither reaches later row sets nor drains the stream before get_return_values() is called; result sets and output parameters can both be missing. Collapse to the first row set before returning to the TypeScript consumer.

        let result = client
            .execute_stored_procedure(stored_proc_name, None, Some(named_params), ())
            .await;

[Theekshna]

Looks good. Would be good to make sure we're covering most edge cases etc in out e2e/unit tests

[Copilot]

Pull request overview

Copilot reviewed 68 out of 68 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

mssql-tds/src/connection/tds_client.rs:1755

• This documentation still describes the removed expose_norow_statements false/true modes. The function now has no such parameter and always applies the count-or-message predicate, so this guidance misstates the unified API's behavior.

    /// With `expose_norow_statements = false` (result-set navigation used by
    /// batch execution and the JS/Python consumers), a no-row statement's DONE
    /// token carrying the MORE flag is skipped so the method advances to the
    /// next COLMETADATA — consecutive no-row statements collapse into the

[David-Engel]

@saurabh500 - This is a breaking API change. But I think it cleans things up nicely and is worth it. Let me know what you think.

[saurabh500]

LGTM