PERF: Native C++ parameter detection and execute pipeline

[Gaurav Sharma (bewithgaurav)]

Work Item / Issue Reference

AB#44979
AB#49196

GitHub Issue: #500

---

Summary

Moves parameter type detection and binding from Python into a native C++ pipeline using raw CPython API calls. The new DDBCSQLExecute handles type detection → parameter binding → SQLExecute in a single FFI crossing, eliminating per-parameter Python overhead entirely.

What changed:

• DetectParamTypes — C++ type detection using raw CPython API (PyLong_Check, PyDateTime_Check, PyObject_RichCompareBool, etc.) replacing the Python-side _create_parameter_types_list loop for the standard execute path.
• DDBCSQLExecute (formerly DDBCSQLExecuteFast) — single C++ pipeline: detect → bind → execute. ParamInfo never crosses the pybind11 boundary.
• DDBCSQLExecuteLegacy (formerly DDBCSQLExecute) — retained for setinputsizes users only, and annotated in-code as slated for removal once those overrides are handled natively.
• MONEY/SMALLMONEY bounds cached once at init using exact Decimal comparison (not lossy double).
• PyTypeCache (py_type_cache.hpp) stores all type objects as raw PyObject* (not py::object), eliminating pybind11 wrapper overhead on every cache hit.
• NUMERIC mantissa built from four fixed-width uint32 limbs instead of walking every Decimal digit through PyNumber_Multiply/PyNumber_Add. SQL Server caps NUMERIC at 38 digits, so the mantissa always fits 128 bits. Decimal detection measured 2.3–2.9x faster on its own.
• Reference ownership is RAII throughout. ParamInfo::dataPtr holds a py::object rather than a raw PyObject* with a hand-written rule of five, and py_ref.hpp provides steal/borrow so every adoption of a CPython reference states whether it is taking a new reference or borrowing one.
• Parameter detection lives in param_detect.hpp rather than inline in the 6600-line ddbc_bindings.cpp. Header-only because the build is -O3 with no LTO, so a .cpp boundary would also be an inlining boundary.

Routing (cursor.py):

# Standard path (99% of calls): no setinputsizes -> all in C++# Legacy path: setinputsizes active -> Python type detection + DDBCSQLExecuteLegacy

---

Performance Results 🚀

The Python-side type detection cost was ~2.0–2.3µs per parameter — an isinstance check, ParamInfo object construction, and a pybind11 FFI boundary crossing per parameter, per execute call. The C++ path replaces this with ~35ns/param (raw PyLong_Check + struct field write) — a ~60x faster per-parameter detection.

macOS arm64 (Apple Silicon M-series), Python 3.13

Scenario	After (C++)	Before	Improvement	Python overhead eliminated
3 params	435µs	444µs	2% faster	10µs saved
10 params	321µs	344µs	7% faster	22µs saved
50 params	394µs	502µs	21% faster	107µs saved
100 params	558µs	770µs	28% faster	212µs saved
200 params	644µs	1.08ms	40% faster	432µs saved
500 params	708µs	1.82ms	61% faster	1.12ms saved
1024 params	1.07ms	3.32ms	68% faster	2.25ms saved

Linux aarch64 (Docker container), Python 3.13

Scenario	After (C++)	Before	Improvement	Python overhead eliminated
3 params	158µs	164µs	4% faster	6µs saved
10 params	159µs	178µs	11% faster	19µs saved
50 params	170µs	271µs	37% faster	101µs saved
100 params	209µs	411µs	49% faster	202µs saved
200 params	280µs	651µs	57% faster	371µs saved
500 params	396µs	1.35ms	71% faster	956µs saved
1024 params	746µs	2.75ms	73% faster	2.0ms saved

vs pyodbc (post-PR, macOS)

Params	mssql-python	pyodbc	Gap
3	399µs	388µs	3% gap (near parity)
50	458µs	452µs	1% gap (parity)
200	604µs	550µs	10% gap (down from ~14x pre-PR)
1024	1.31ms	979µs	33% gap (binding overhead, addressable separately)

Customer scenarios (end to end, macOS arm64)

The numbers above isolate driver overhead. These are whole insert workloads, so they also carry the network round trip and SQL Server actually writing the rows, which this PR does not change and which dilutes the percentage. Measured against the merge base (d94debd) with the two builds interleaved across 3 rounds, 7 iterations each, first 2 discarded.

Scenario	Before	After	Speedup
Orders insert (int, varchar, decimal, datetime2)	880.6ms	561.0ms	1.57x
Event log insert (uuid, datetime2, varchar, int)	827.2ms	533.5ms	1.55x
Document insert (nvarchar(max) ~10KB, DAE)	1622.0ms	1021.3ms	1.59x
Wide row insert (50 mixed columns)	1598.6ms	1048.9ms	1.52x
Single-row execute x5000 (4 params)	2103.5ms	2095.9ms	1.00x

Between them these cover every parameter type whose detection moved: int, varchar, decimal, datetime2, uuid, and the nvarchar(max) DAE streaming path.

Single-row execute does not move, and that is the expected result rather than a disappointment. At roughly 420µs per call the cost is the network round trip; detection for 4 parameters was only ever about 9µs of it. The gain scales with parameters per execute, so batched and wide-row work benefits and one-row-at-a-time work stays where it was.

Bottom line

Metric	Value
Avg improvement (50+ params)	~50% faster execute()
Worst-case improvement (1024 params)	73% faster (2ms saved per call)
Per-param overhead reduction	~60x (2.3µs → 35ns)
pyodbc gap closed	From 14x slower (GH-500) to <10% gap at 200 params
Real-world impact	Bulk inserts see 1.5–1.6x throughput end to end (customer scenarios above)

---

Checklist

• Tested locally (macOS arm64 + Linux aarch64)
• Verified perf gain with micro-benchmarks on both platforms, and with end-to-end customer scenarios against the merge base
• CI passing (CodeQL, DevSkim, Black, C++ lint)
• No breaking changes to public API
• setinputsizes users unaffected (routed to legacy path)

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 89%

🎯 Overall Coverage 82%

📈 Total Lines Covered:7751 out of 9430 📁 Project:mssql-python

---

Diff Coverage

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

• mssql_python/cursor.py (100%)
• mssql_python/pybind/ddbc_bindings.cpp (81.8%): Missing lines 247,576-577,639,707,1810-1811,1954-1955,2050-2051,2054-2057,2069-2077,2102-2103,2133-2135,2156,2173,2189-2192,2202,2621,2736,4422
• mssql_python/pybind/ddbc_bindings.h (100%)
• mssql_python/pybind/param_detect.hpp (91.6%): Missing lines 275-276,282-283,424-425,431-432,456-457,469-474,507-512,546-547,563-564,580-581,612-613,658-659
• mssql_python/pybind/py_ref.hpp (100%)
• mssql_python/pybind/py_type_cache.hpp (92.7%): Missing lines 48-51

Summary

• Total: 693 lines
• Missing: 75 lines
• Coverage: 89%

mssql_python/pybind/ddbc_bindings.cpp

Lines 243-251

243 SQLDescribeParamFunc SQLDescribeParam_ptr = nullptr;
244245namespace {
246 ! 247248constchar* GetSqlCTypeAsString(constSQLSMALLINT cType) {
249switch (cType) {
250STRINGIFY_FOR_CASE(SQL_C_CHAR);
251STRINGIFY_FOR_CASE(SQL_C_WCHAR);

---

Lines 572-581

572 dataPtr = sqlwcharBuffer->data();
573 bufferLength = sqlwcharBuffer->size() * sizeof(SQLWCHAR);
574 strLenOrIndPtr = AllocateParamBuffer<SQLLEN>(paramBuffers);
575// Use explicit byte length instead of SQL_NTS so embedded NUL chars
! 576// aren't treated as string terminators.
! 577 *strLenOrIndPtr = static_cast<SQLLEN>(sqlwcharBuffer->size() * sizeof(SQLWCHAR));
578 }
579break;
580 }
581caseSQL_C_BIT: {

---

Lines 635-643

635caseSQL_C_LONG: {
636if (!py::isinstance<py::int_>(param)) {
637ThrowStdException(MakeParamMismatchErrorStr(paramInfo.paramCType, paramIndex));
638 }
! 639// Both detection paths (DetectParamTypes / _map_sql_type) reject out-of-int64640// ints before binding, so those callers only reach here with bindable values.641// A setinputsizes() override that forces SQL_C_SBIGINT on an out-of-range int642// skips detection; that value fails the cast below, same as before this change.643 dataPtr = static_cast<void*>(

---

Lines 703-711

703 dataPtr = static_cast<void*>(sqlTimePtr);
704break;
705 }
706caseSQL_C_SS_TIMESTAMPOFFSET: {
! 707 py::object datetimeType = PyTypeCache::get_datetime_class_obj();
708if (!py::isinstance(param, datetimeType)) {
709ThrowStdException(MakeParamMismatchErrorStr(paramInfo.paramCType, paramIndex));
710 }
711// Checking if the object has a timezone

---

Lines 1806-1815

18061807// LEGACY — slated for removal in a future optimization round.1808//1809// Executes the provided query using a ParamInfo list that Python already built,
! 1810// rather than detecting parameter types in C++. Retained only for setinputsizes()
! 1811// callers, whose explicit type overrides the native path does not yet honour.1812// Every parameter crosses the pybind11 boundary as a ParamInfo object here, which1813// is the cost SQLExecute_wrap exists to avoid. Once setinputsizes is handled1814// natively this function and its DDBCSQLExecuteLegacy binding both go away.1815//

---

Lines 1950-1959

1950if (matchedInfo->paramCType == SQL_C_WCHAR) {
1951 std::u16string utf16 =
1952 borrow<py::str>(pyObj).cast<std::u16string>();
1953 rc = stream_dae_chunks(
! 1954reinterpretU16stringAsSqlWChar(utf16),
! 1955 utf16.size() * sizeof(SQLWCHAR),
1956 putData);
1957if (!SQL_SUCCEEDED(rc)) {
1958LOG("SQLExecute: SQLPutData failed for SQL_C_WCHAR DAE streaming");
1959return rc;

---

Lines 2046-2061

2046returnSQL_INVALID_HANDLE;
2047 }
20482049SQLHANDLE hStmt = statementHandle->get();
! 2050 ! 2051// Configure forward-only / read-only cursor (matches slow path semantics).2052if (SQLSetStmtAttr_ptr) {
2053SQLSetStmtAttr_ptr(hStmt, SQL_ATTR_CURSOR_TYPE,
! 2054 (SQLPOINTER)SQL_CURSOR_FORWARD_ONLY, 0);
! 2055SQLSetStmtAttr_ptr(hStmt, SQL_ATTR_CONCURRENCY,
! 2056 (SQLPOINTER)SQL_CONCUR_READ_ONLY, 0);
! 2057 }
20582059// The encoding-settings dict has the form {"encoding": str, "ctype": int}.2060// Note: the Python layer's SQL_C_CHAR constant is numerically -8, the same2061// as ODBC's SQL_C_WCHAR. As a result, the only path that genuinely uses

---

Lines 2065-2081

2065// encoding when ctype == 1 (real ODBC SQL_CHAR). Otherwise the user's2066// "encoding" value is meant for the wide-char path and we leave it alone.2067 std::string charEncoding = "utf-8";
2068if (encoding_settings.contains("ctype") && encoding_settings.contains("encoding")) {
! 2069int ctype = encoding_settings["ctype"].cast<int>();
! 2070if (ctype == SQL_C_CHAR/* real ODBC value: 1 */) {
! 2071 charEncoding = encoding_settings["encoding"].cast<std::string>();
! 2072 }
! 2073 }
! 2074 ! 2075// The cursor.py caller always passes a fresh `list(actual_params)` so this
! 2076// function is free to mutate slots in place. Even so, every site below uses
! 2077// PyList_SetItem (which decrefs the old slot before stealing the new ref),2078// so the function is safe regardless of who owns the list.20792080// Run DetectParamTypes BEFORE SQLPrepare so that type-detection errors2081// (unsupported type, NaN Decimal, precision overflow) don't leave the

---

Lines 2098-2107

2098 }
2099if (!SQL_SUCCEEDED(rc)) return rc;
2100 statementHandle->clearDescribeCache();
2101 is_stmt_prepared[0] = py::bool_(true);
! 2102 } else {
! 2103ThrowStdException("Cannot execute unprepared statement");
2104 }
2105 }
21062107 std::vector<std::shared_ptr<void>> paramBuffers;

---

Lines 2129-2139

2129 rc = SQLParamData_ptr(hStmt, &paramToken);
2130 }
2131if (rc != SQL_NEED_DATA) break;
2132 ! 2133// The DAE token is the &paramInfos[i] we handed to SQLBindParameter as the
! 2134// parameter value (see BindParameters), and paramInfos is sized up front and
! 2135// never reallocated, so the token casts straight back to its ParamInfo instead2136// of scanning. Range-check it against the vector before trusting it, so a bogus2137// token throws rather than dereferencing arbitrary memory.2138const ParamInfo* matchedInfo = reinterpret_cast<const ParamInfo*>(paramToken);
2139const ParamInfo* first = paramInfos.data();

---

Lines 2152-2160

2152if (matchedInfo->paramCType == SQL_C_WCHAR) {
2153 std::u16string u16 =
2154 borrow<py::str>(pyObj).cast<std::u16string>();
2155 rc = stream_dae_chunks(
! 2156reinterpretU16stringAsSqlWChar(u16),
2157u16.size() * sizeof(SQLWCHAR),
2158 putData);
2159if (!SQL_SUCCEEDED(rc)) return rc;
2160 } elseif (matchedInfo->paramCType == SQL_C_CHAR) {

---

Lines 2169-2177

2169 }
2170 } elseif (PyBytes_Check(pyObj) || PyByteArray_Check(pyObj)) {
2171// matchedInfo->dataPtr holds a strong ref to pyObj for the whole loop.2172constchar* dataPtr = nullptr;
! 2173size_t totalBytes = 0;
2174 std::string bytesStorage; // only used for the bytearray copy below21752176if (PyBytes_Check(pyObj)) {
2177// bytes is immutable and kept alive by the strong ref above, so stream

---

Lines 2185-2196

2185 bytesStorage.assign(PyByteArray_AS_STRING(pyObj),
2186static_cast<size_t>(PyByteArray_GET_SIZE(pyObj)));
2187 dataPtr = bytesStorage.data();
2188 totalBytes = bytesStorage.size();
! 2189 }
! 2190 ! 2191 rc = stream_dae_chunks(dataPtr, totalBytes, putData);
! 2192if (!SQL_SUCCEEDED(rc)) return rc;
2193 } else {
2194ThrowStdException("SQLExecute: DAE only supported for str or bytes");
2195 }
2196 }

---

Lines 2198-2206

2198 }
21992200if (!SQL_SUCCEEDED(rc) && rc != SQL_NO_DATA) return rc;
2201 ! 2202// Unbind parameter buffers before they go out of scope.2203// Not called on error paths — diagnostics must remain readable.2204SQLRETURN exec_rc = rc;
2205SQLFreeStmt_ptr(hStmt, SQL_RESET_PARAMS);
2206return exec_rc;

---

Lines 2617-2625

2617 DateTimeOffset* dtoArray =
2618 AllocateParamBufferArray<DateTimeOffset>(tempBuffers, paramSetSize);
2619 strLenOrIndArray = AllocateParamBufferArray<SQLLEN>(tempBuffers, paramSetSize);
2620 ! 2621 py::object datetimeType = PyTypeCache::get_datetime_class_obj();
26222623for (size_t i = 0; i < paramSetSize; ++i) {
2624const py::handle& param = columnValues[i];

---

Lines 2732-2740

27322733// Get cached UUID class from module-level helper2734// This avoids static object destruction issues during2735// Python finalization
! 2736 py::object uuid_class = PyTypeCache::get_uuid_class_obj();
2737// Get cached UUID class27382739for (size_t i = 0; i < paramSetSize; ++i) {
2740const py::handle& element = columnValues[i];

---

Lines 4418-4426

4418break;
4419 }
4420caseSQL_TYPE_DATE: {
4421 PyObject* dateObj =
! 4422PyTypeCache::get_date_class_obj()(buffers.dateBuffers[col - 1][i].year,
4423 buffers.dateBuffers[col - 1][i].month,
4424 buffers.dateBuffers[col - 1][i].day)
4425 .release()
4426 .ptr();

---

mssql_python/pybind/param_detect.hpp

Lines 271-280

271if (!as_str) {
272// PyObject_Str can fail (e.g. CPython's int->str digit limit for a273// multi-thousand-digit int). Drop that error and fall back to a274// placeholder so we still raise our own clear ValueError.
! 275PyErr_Clear();
! 276 }
277 std::string s = as_str ? as_str.cast<std::string>() : std::string("<int>");
278throwpy::value_error("integer " + s +
279" is out of range for SQL BIGINT [-2^63, 2^63-1]");
280 } else {

---

Lines 278-287

278throwpy::value_error("integer " + s +
279" is out of range for SQL BIGINT [-2^63, 2^63-1]");
280 } else {
281// A real Python error from PyLong_AsLongLongAndOverflow, not overflow.
! 282throwpy::error_already_set();
! 283 }
284 info.decimalDigits = 0;
285continue;
286 }

---

Lines 420-429

420// so calling the same method is what keeps the two paths in agreement.421 py::object time_obj = steal(PyObject_CallMethod(obj, "isoformat", "s", "microseconds"));
422if (!time_obj) throwpy::error_already_set();
423if (!PyUnicode_Check(time_obj.ptr())) {
! 424throwpy::type_error("datetime.time.isoformat() must return a str");
! 425 }
426 Py_ssize_t time_len = PyUnicode_GET_LENGTH(time_obj.ptr());
427 info.columnSize = std::max<SQLULEN>(info.columnSize, time_len);
428// PyList_SetItem (lowercase) decrefs the old slot before stealing the new429// reference; safe here because cursor.py already passed a fresh list copy.

---

Lines 427-436

427 info.columnSize = std::max<SQLULEN>(info.columnSize, time_len);
428// PyList_SetItem (lowercase) decrefs the old slot before stealing the new429// reference; safe here because cursor.py already passed a fresh list copy.430if (PyList_SetItem(params, i, time_obj.release().ptr()) != 0) {
! 431throwpy::error_already_set();
! 432 }
433continue;
434 }
435436// --- Decimal ---

---

Lines 452-461

452 py::object digits_obj = steal(PyObject_GetAttrString(as_tuple_ptr.ptr(), "digits"));
453if (!digits_obj) throwpy::error_already_set();
454455if (!PyTuple_Check(digits_obj.ptr())) {
! 456throwpy::type_error("Decimal.as_tuple().digits must be a tuple");
! 457 }
458459 Py_ssize_t num_digits = PyTuple_GET_SIZE(digits_obj.ptr());
460461// Read the exponent at full width and range-check it BEFORE narrowing to int.

---

Lines 465-478

465// any precision, so treat overflow as precision overflow rather than propagating466// OverflowError, matching what the legacy Python path reports.467longlong exponent_ll = PyLong_AsLongLong(exponent_obj.ptr());
468if (exponent_ll == -1 && PyErr_Occurred()) {
! 469PyErr_Clear();
! 470throwpy::value_error(
! 471"Precision of the numeric value is too high. "
! 472"The maximum precision supported by SQL Server is " +
! 473std::to_string(MAX_NUMERIC_PRECISION) + ".");
! 474 }
475// Bound before any arithmetic or negation. MAX_NUMERIC_PRECISION on both sides is476// wider than anything bindable, and keeps -exponent well clear of INT_MIN, whose477// negation would be signed-overflow UB.478if (exponent_ll > MAX_NUMERIC_PRECISION || exponent_ll < -MAX_NUMERIC_PRECISION) {

---

Lines 503-516

503else504 precision = -exponent;
505506if (precision > MAX_NUMERIC_PRECISION) {
! 507throwpy::value_error(
! 508"Precision of the numeric value is too high. "
! 509"The maximum precision supported by SQL Server is " +
! 510std::to_string(MAX_NUMERIC_PRECISION) + ", but got " +
! 511std::to_string(precision) + ".");
! 512 }
513514// Check SMALLMONEY first, then widen to MONEY, so common small values keep the narrowest515// exact range while still accepting larger fixed-point values supported by SQL Server.516// MONEY/SMALLMONEY: SQL Server stores these as fixed-point integers internally.

---

Lines 542-551

542 PyObject* raw = formatted.release().ptr();
543if (PyList_SetItem(params, i, raw) != 0) {
544// PyList_SetItem steals (decrefs) the item even on failure,545// so raw is already freed — do NOT Py_DECREF here.
! 546throwpy::error_already_set();
! 547 }
548continue;
549 }
550551// Build SQL_NUMERIC_STRUCT from the Decimal object. Store as a pybind11-castable

---

Lines 559-568

559 py::object numeric_obj = py::cast(nd);
560 PyObject* raw = numeric_obj.release().ptr();
561if (PyList_SetItem(params, i, raw) != 0) {
562// PyList_SetItem steals (decrefs) the item even on failure.
! 563throwpy::error_already_set();
! 564 }
565continue;
566 }
567568// --- UUID ---

---

Lines 576-585

576 info.columnSize = 16;
577 info.decimalDigits = 0;
578if (PyList_SetItem(params, i, bytes_le) != 0) {
579// PyList_SetItem steals (decrefs) the item even on failure.
! 580throwpy::error_already_set();
! 581 }
582continue;
583 }
584585// --- Unknown type: raise TypeError (matches Python _map_sql_type) ---

---

Lines 608-617

608int sign_val = static_cast<int>(PyLong_AsLong(sign_obj.ptr()));
609if (sign_val == -1 && PyErr_Occurred()) throwpy::error_already_set();
610611if (!PyTuple_Check(digits)) {
! 612throwpy::type_error("Decimal.as_tuple().digits must be a tuple");
! 613 }
614615// SQL Server precision counts all stored decimal digits, while scale is just the616// fractional digits. A positive exponent moves trailing zeros into the integer part;617// a negative exponent means scale = -exponent and precision must still cover leading

---

Lines 654-663

654for (int j = 0; j < exponent; ++j) {
655 overflow |= mul10_add(0);
656 }
657if (overflow != 0) {
! 658throwpy::value_error("Decimal magnitude exceeds the 16-byte SQL NUMERIC capacity");
! 659 }
660661 NumericData nd;
662 nd.precision = static_cast<SQLCHAR>(precision);
663 nd.scale = static_cast<SQLSCHAR>(scale);

---

mssql_python/pybind/py_type_cache.hpp

Lines 44-55

44// type detection in Python and can therefore reach here without the cache being warm;45// it can be dropped once that path is removed.46inline PyObject* get_cached_class(PyObject* cached, constchar* module_name, constchar* attr_name) {
47if (cache_initialized && cached) return cached;
! 48 py::object mod = steal(PyImport_ImportModule(module_name));
! 49if (!mod) returnnullptr;
! 50returnPyObject_GetAttrString(mod.ptr(), attr_name);
! 51 }
5253// One-time init. Uses local py::objects so exception cleanup is automatic;54// only .release() into globals after ALL acquisitions succeed.55inlinevoidinitialize() {

---

---

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.pybind.ddbc_bindings.h: 61.5%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.pybind.ddbc_bindings.cpp: 75.5%
mssql_python.__init__.py: 77.6%
mssql_python.row.py: 77.6%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.pybind.connection.connection_pool.cpp: 81.4%
mssql_python.pybind.connection.connection.cpp: 84.3%
mssql_python.logging.py: 85.5%

---

🔗 Quick Links

⚙️ Build Summary	📋 Coverage Details
View Azure DevOps Build	Browse Full Coverage Report

[Sumit Sarabhai (sumitmsft)]

Nice work! I tried to trace the refcounting (steal/borrow RAII), GIL release around ODBC calls, DAE streaming, and legacy parity; it all holds up.

One optional, non-blocking follow-up:
"2**63" classifies as BIGINT and fails later at "param.cast<int64_t>()" with a generic message. This matches legacy "_map_sql_type" exactly, so it's faithful parity, not a regression. For a clearer "exceeds BIGINT range" error, raise at detect time on both paths. (Minor: the int64_t range guard in the bind case is dead code.) // Ref: param_detect.hpp

[gargsaumya]

LGTM. Earlier reviews covered the substantive items, approved.