PERF: Native C++ parameter detection and execute pipeline

[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 primary 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.
• MONEY/SMALLMONEY bounds cached once at init using exact Decimal comparison (not lossy double).
• PythonObjectCache stores all type objects as raw PyObject* (not py::object), eliminating pybind11 wrapper overhead on every cache hit.
• Proper Py_DECREF cleanup and PyObject_IsInstance error handling on all paths.

Routing (cursor.py):

# Primary 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)

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 with 200+ params see 2–3x throughput gain

---

Checklist

• Tested locally (macOS arm64 + Linux aarch64)
• Verified perf gain with micro-benchmarks on both platforms
• 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 90%

🎯 Overall Coverage 81%

📈 Total Lines Covered: 7429 out of 9125 📁 Project: mssql-python

---

Diff Coverage

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

• mssql_python/cursor.py (100%)
• mssql_python/pybind/ddbc_bindings.cpp (89.4%): Missing lines 346,669-670,694-695,752-753,769-770,786-787,818-819,864-865,1140-1141,1282,2475-2476,2570-2571,2574-2577,2589-2597,2620-2621,2651-2653,2663-2667,2671,2677,2697,2713-2716,2726,3269,4358
• mssql_python/pybind/py_type_cache.hpp (93.0%): Missing lines 58-61

Summary

• Total: 590 lines
• Missing: 59 lines
• Coverage: 90%

mssql_python/pybind/ddbc_bindings.cpp

Lines 342-350

  342 SQLDescribeParamFunc SQLDescribeParam_ptr = nullptr;
  343 
  344 namespace {
  345 
! 346 
  347 const char* GetSqlCTypeAsString(const SQLSMALLINT cType) {
  348     switch (cType) {
  349         STRINGIFY_FOR_CASE(SQL_C_CHAR);
  350         STRINGIFY_FOR_CASE(SQL_C_WCHAR);

---

Lines 665-674

  665             Py_ssize_t time_len = PyUnicode_GET_LENGTH(time_str);
  666             info.columnSize = std::max<SQLULEN>(info.columnSize, time_len);
  667             // PyList_SetItem (lowercase) decrefs the old slot before stealing the new
  668             // reference; safe here because cursor.py already passed a fresh list copy.
! 669             if (PyList_SetItem(params, i, time_str) != 0) {
! 670                 throw py::error_already_set();
  671             }
  672             continue;
  673         }

---

Lines 690-699

  690 
  691             py::object digits_obj = steal(PyObject_GetAttrString(as_tuple_ptr.ptr(), "digits"));
  692             if (!digits_obj) throw py::error_already_set();
  693 
! 694             if (!PyTuple_Check(digits_obj.ptr())) {
! 695                 throw py::type_error("Decimal.as_tuple().digits must be a tuple");
  696             }
  697 
  698             Py_ssize_t num_digits = PyTuple_GET_SIZE(digits_obj.ptr());
  699             int exponent = static_cast<int>(PyLong_AsLong(exponent_obj.ptr()));

---

Lines 748-757

  748                 info.decimalDigits = 0;
  749                 PyObject* raw = formatted.release().ptr();
  750                 if (PyList_SetItem(params, i, raw) != 0) {
  751                     // PyList_SetItem steals (decrefs) the item even on failure,
! 752                     // so raw is already freed — do NOT Py_DECREF here.
! 753                     throw py::error_already_set();
  754                 }
  755                 continue;
  756             }

---

Lines 765-774

  765             // Store NumericData as a Python object in the param list for the binder.
  766             py::object numeric_obj = py::cast(nd);
  767             PyObject* raw = numeric_obj.release().ptr();
  768             if (PyList_SetItem(params, i, raw) != 0) {
! 769                 // PyList_SetItem steals (decrefs) the item even on failure.
! 770                 throw py::error_already_set();
  771             }
  772             continue;
  773         }

---

Lines 782-791

  782             info.paramCType = SQL_C_GUID;
  783             info.columnSize = 16;
  784             info.decimalDigits = 0;
  785             if (PyList_SetItem(params, i, bytes_le) != 0) {
! 786                 // PyList_SetItem steals (decrefs) the item even on failure.
! 787                 throw py::error_already_set();
  788             }
  789             continue;
  790         }

---

Lines 814-823

  814     if (!sign_obj) throw py::error_already_set();
  815     int sign_val = static_cast<int>(PyLong_AsLong(sign_obj.ptr()));
  816     if (sign_val == -1 && PyErr_Occurred()) throw py::error_already_set();
  817 
! 818     if (!PyTuple_Check(digits)) {
! 819         throw py::type_error("Decimal.as_tuple().digits must be a tuple");
  820     }
  821 
  822     // SQL Server precision counts all stored decimal digits, while scale is just the
  823     // fractional digits. A positive exponent moves trailing zeros into the integer part;

---

Lines 860-869

  860     // must become mantissa 12300 before packing.
  861     for (int j = 0; j < exponent; ++j) {
  862         overflow |= mul10_add(0);
  863     }
! 864     if (overflow != 0) {
! 865         throw py::value_error("Decimal magnitude exceeds the 16-byte SQL NUMERIC capacity");
  866     }
  867 
  868     NumericData nd;
  869     nd.precision = static_cast<SQLCHAR>(precision);

---

Lines 1136-1145

  1136                     dataPtr = sqlwcharBuffer->data();
  1137                     bufferLength = sqlwcharBuffer->size() * sizeof(SQLWCHAR);
  1138                     strLenOrIndPtr = AllocateParamBuffer<SQLLEN>(paramBuffers);
  1139                     // Use explicit byte length instead of SQL_NTS so embedded NUL chars
! 1140                     // aren't treated as string terminators.
! 1141                     *strLenOrIndPtr = static_cast<SQLLEN>(sqlwcharBuffer->size() * sizeof(SQLWCHAR));
  1142                 }
  1143                 break;
  1144             }
  1145             case SQL_C_BIT: {

---

Lines 1278-1286

  1278                 dataPtr = static_cast<void*>(sqlTimePtr);
  1279                 break;
  1280             }
  1281             case SQL_C_SS_TIMESTAMPOFFSET: {
! 1282                 py::object datetimeType = PyTypeCache::get_datetime_class_obj();
  1283                 if (!py::isinstance(param, datetimeType)) {
  1284                     ThrowStdException(MakeParamMismatchErrorStr(paramInfo.paramCType, paramIndex));
  1285                 }
  1286                 // Checking if the object has a timezone

---

Lines 2471-2480

  2471                     continue;
  2472                 }
  2473                 if (PyUnicode_Check(pyObj)) {
  2474                     if (matchedInfo->paramCType == SQL_C_WCHAR) {
! 2475                         std::u16string utf16 =
! 2476                             borrow<py::str>(pyObj).cast<std::u16string>();
  2477                         rc = stream_dae_chunks(
  2478                             reinterpretU16stringAsSqlWChar(utf16),
  2479                             utf16.size() * sizeof(SQLWCHAR),
  2480                             putData);

---

Lines 2566-2581

  2566                               py::list is_stmt_prepared,
  2567                               bool use_prepare,
  2568                               const py::dict& encoding_settings) {
  2569     if (!statementHandle || !statementHandle->get()) {
! 2570         return SQL_INVALID_HANDLE;
! 2571     }
  2572 
  2573     SQLHANDLE hStmt = statementHandle->get();
! 2574 
! 2575     // Configure forward-only / read-only cursor (matches slow path semantics).
! 2576     if (SQLSetStmtAttr_ptr) {
! 2577         SQLSetStmtAttr_ptr(hStmt, SQL_ATTR_CURSOR_TYPE,
  2578                            (SQLPOINTER)SQL_CURSOR_FORWARD_ONLY, 0);
  2579         SQLSetStmtAttr_ptr(hStmt, SQL_ATTR_CONCURRENCY,
  2580                            (SQLPOINTER)SQL_CONCUR_READ_ONLY, 0);
  2581     }

---

Lines 2585-2601

  2585     // as ODBC's SQL_C_WCHAR. As a result, the only path that genuinely uses
  2586     // byte-level character encoding is when the user explicitly opts in via
  2587     // setencoding(..., ctype=mssql_python.SQL_CHAR) (which sends ctype=1, the
  2588     // real ODBC SQL_CHAR). We default to utf-8 and only honor the dict's
! 2589     // encoding when ctype == 1 (real ODBC SQL_CHAR). Otherwise the user's
! 2590     // "encoding" value is meant for the wide-char path and we leave it alone.
! 2591     std::string charEncoding = "utf-8";
! 2592     if (encoding_settings.contains("ctype") && encoding_settings.contains("encoding")) {
! 2593         int ctype = encoding_settings["ctype"].cast<int>();
! 2594         if (ctype == SQL_C_CHAR /* real ODBC value: 1 */) {
! 2595             charEncoding = encoding_settings["encoding"].cast<std::string>();
! 2596         }
! 2597     }
  2598 
  2599     // The cursor.py caller always passes a fresh `list(actual_params)` so this
  2600     // function is free to mutate slots in place. Even so, every site below uses
  2601     // PyList_SetItem (which decrefs the old slot before stealing the new ref),

---

Lines 2616-2625

  2616     if (!already_prepared) {
  2617         if (use_prepare) {
  2618             SQLWCHAR* queryPtr = reinterpretU16stringAsSqlWChar(query);
  2619             {
! 2620                 py::gil_scoped_release release;
! 2621                 rc = SQLPrepare_ptr(hStmt, queryPtr, SQL_NTS);
  2622             }
  2623             if (!SQL_SUCCEEDED(rc)) return rc;
  2624             statementHandle->clearDescribeCache();
  2625             is_stmt_prepared[0] = py::bool_(true);

---

Lines 2647-2657

  2647             py::gil_scoped_release release;
  2648             return SQLPutData_ptr(hStmt, data, len);
  2649         };
  2650         while (true) {
! 2651             {
! 2652                 py::gil_scoped_release release;
! 2653                 rc = SQLParamData_ptr(hStmt, &paramToken);
  2654             }
  2655             if (rc != SQL_NEED_DATA) break;
  2656 
  2657             const ParamInfo* matchedInfo = nullptr;

---

Lines 2659-2675

  2659                 if (reinterpret_cast<SQLPOINTER>(const_cast<ParamInfo*>(&info)) == paramToken) {
  2660                     matchedInfo = &info;
  2661                     break;
  2662                 }
! 2663             }
! 2664             if (!matchedInfo) {
! 2665                 ThrowStdException("SQLExecuteFast: unrecognized paramToken from SQLParamData");
! 2666             }
! 2667             PyObject* pyObj = matchedInfo->dataPtr.ptr();
  2668             if (!pyObj || pyObj == Py_None) {
  2669                 py::gil_scoped_release release;
  2670                 SQLPutData_ptr(hStmt, nullptr, 0);
! 2671                 continue;
  2672             }
  2673 
  2674             if (PyUnicode_Check(pyObj)) {
  2675                 if (matchedInfo->paramCType == SQL_C_WCHAR) {

---

Lines 2673-2681

  2673 
  2674             if (PyUnicode_Check(pyObj)) {
  2675                 if (matchedInfo->paramCType == SQL_C_WCHAR) {
  2676                     std::u16string u16 =
! 2677                         borrow<py::str>(pyObj).cast<std::u16string>();
  2678                     rc = stream_dae_chunks(
  2679                         reinterpretU16stringAsSqlWChar(u16),
  2680                         u16.size() * sizeof(SQLWCHAR),
  2681                         putData);

---

Lines 2693-2701

  2693             } else if (PyBytes_Check(pyObj) || PyByteArray_Check(pyObj)) {
  2694                 // Handle bytes and bytearray separately — pybind11's bytes
  2695                 // caster does not safely convert bytearray.
  2696                 const char* dataPtr = nullptr;
! 2697                 size_t totalBytes = 0;
  2698                 std::string bytesStorage;  // lifetime must span the loop
  2699 
  2700                 if (PyBytes_Check(pyObj)) {
  2701                     bytesStorage = borrow<py::bytes>(pyObj);

---

Lines 2709-2720

  2709                     totalBytes = bytesStorage.size();
  2710                 }
  2711 
  2712                 rc = stream_dae_chunks(dataPtr, totalBytes, putData);
! 2713                 if (!SQL_SUCCEEDED(rc)) return rc;
! 2714             } else {
! 2715                 ThrowStdException("SQLExecuteFast: DAE only supported for str or bytes");
! 2716             }
  2717         }
  2718         if (!SQL_SUCCEEDED(rc) && rc != SQL_NO_DATA) return rc;
  2719     }

---

Lines 2722-2730

  2722 
  2723     // Unbind parameter buffers before they go out of scope.
  2724     // Not called on error paths — diagnostics must remain readable.
  2725     SQLRETURN exec_rc = rc;
! 2726     SQLFreeStmt_ptr(hStmt, SQL_RESET_PARAMS);
  2727     return exec_rc;
  2728 }
  2729 
  2730 SQLRETURN BindParameterArray(SqlHandle& handle, SQLHANDLE hStmt, const py::list& columnwise_params,

---

Lines 3265-3273

  3265 
  3266                     // Get cached UUID class from module-level helper
  3267                     // This avoids static object destruction issues during
  3268                     // Python finalization
! 3269                     py::object uuid_class = PyTypeCache::get_uuid_class_obj();
  3270                     // Get cached UUID class
  3271 
  3272                     for (size_t i = 0; i < paramSetSize; ++i) {
  3273                         const py::handle& element = columnValues[i];

---

Lines 4354-4362

  4354                     int microseconds = dtoValue.fraction / 1000;
  4355                     py::object datetime_module = py::module_::import("datetime");
  4356                     py::object tzinfo = datetime_module.attr("timezone")(
  4357                         datetime_module.attr("timedelta")(py::arg("minutes") = totalMinutes));
! 4358                     py::object py_dt = PyTypeCache::get_datetime_class_obj()(
  4359                         dtoValue.year, dtoValue.month, dtoValue.day, dtoValue.hour, dtoValue.minute,
  4360                         dtoValue.second, microseconds, tzinfo);
  4361                     row.append(py_dt);
  4362                 } else {

---

mssql_python/pybind/py_type_cache.hpp

Lines 54-65

  54 // Return cached type, falling back to import for legacy paths that call
  55 // before initialize() has run.
  56 inline PyObject* get_cached_class(PyObject* cached, const char* module_name, const char* attr_name) {
  57     if (cache_initialized && cached) return cached;
! 58     py::object mod = steal(PyImport_ImportModule(module_name));
! 59     if (!mod) return nullptr;
! 60     return PyObject_GetAttrString(mod.ptr(), attr_name);
! 61 }
  62 
  63 // One-time init. Uses local py::objects so exception cleanup is automatic;
  64 // only .release() into globals after ALL acquisitions succeed.
  65 inline void initialize() {

---

---

📋 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: 59.9%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.pybind.ddbc_bindings.cpp: 76.7%
mssql_python.__init__.py: 77.3%
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: 83.7%
mssql_python.connection.py: 84.7%

---

🔗 Quick Links

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

[Copilot]

Pull request overview

This PR shifts the primary cursor.execute() pipeline from Python into native C++ by adding a raw-CPython DetectParamTypes fast path and routing calls to a single DDBCSQLExecute FFI entrypoint when setinputsizes isn’t active, targeting large parameter-count performance regressions (GH-500).

Changes:

• Added a native DetectParamTypes → BindParameters → SQLExecute pipeline (DDBCSQLExecute) to avoid per-parameter Python/pybind11 overhead.
• Preserved a legacy path (DDBCSQLExecuteLegacy) for setinputsizes users and updated Python routing accordingly.
• Added parity and regression tests covering fast/slow path equivalence, subclass handling, DAE streaming, and refcount safety.

Reviewed changes

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

File	Description
tests/test_023_fast_path_parity.py	Adds fast-vs-legacy parity tests and regression coverage for the new native execute pipeline.
tests/test_010_pybind_functions.py	Updates exposed-function expectations to include DDBCSQLExecuteLegacy.
mssql_python/pybind/ddbc_bindings.cpp	Implements native type detection, new execute entrypoints, and various binding/DAE handling updates.
mssql_python/cursor.py	Routes execute() to DDBCSQLExecute for the primary path and to DDBCSQLExecuteLegacy when setinputsizes overrides are present.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.