FIX: Release GIL around teardown SQLFreeHandle/SQLFreeStmt (#565)

[saurabh500]

Work Item / Issue Reference

GitHub Issue: #565

---

Summary

Fixes two distinct GIL-held ODBC network round-trips that deadlock when the
connection is routed through an in-process Python TCP forwarder (the
SSH-tunnel-style scenario reported on issue #565). When the GIL is held
across a blocking network syscall, the Python-implemented forwarder thread
cannot acquire the GIL to pump bytes, and the whole interpreter wedges.

Two commits, two independent deadlock sites:

1. Teardown path (9a3b84c6)

SqlHandle::free(), SqlHandle::close_cursor() and SQLFreeHandle_wrap()
call SQLFreeHandle / SQLFreeStmt(SQL_CLOSE) while holding the GIL.
For a statement with an open server-side cursor, both of those issue a
network round-trip to close it. Hit on every conn.close() /
cursor.close() after a parametrized query — matches jschuba's latest repro
comment exactly.

Fix: release the GIL around those three calls. Because two of the three
sites are reachable from C++ destructors (which can run during interpreter
finalization), the release is guarded by !is_python_finalizing() && PyGILState_Check() to avoid PyEval_SaveThread aborts during shutdown.

2. Parametrized-query introspection path (898bd29a)

BindParameters() calls SQLDescribeParam while holding the GIL whenever
a parameter has SQL_UNKNOWN_TYPE (e.g. None argument). The MS ODBC
driver implements this as a sp_describe_undeclared_parameters server
round-trip, so it deadlocks the forwarder thread on every parametrized
query that includes a None value.

Fix: release the GIL around the SQLDescribeParam call.

Note on scope: an earlier draft of this audit also wrapped
Connection::isAlive(), Connection::getInfo() and
Connection::getAutocommit(). Those were dropped after empirical
verification — SQL_ATTR_CONNECTION_DEAD and SQL_ATTR_AUTOCOMMIT GETs
are driver-cached client-side state per the ODBC spec (MSDN explicitly
states SQL_ATTR_CONNECTION_DEAD "does not query the data source for
activity"), and SQLGetInfo for the standard info types returns data the
driver cached at login time. None of those are network calls, so the
GIL release was unnecessary.

Test coverage

Two new tests in tests/test_023_ssh_tunnel_gil_release.py, both using
the existing in-process TCP forwarder + 30s watchdog pattern:

• test_param_query_close_through_python_tcp_forwarder_does_not_deadlock
  reproduces jschuba's repro: parametrized SELECT + fetch + conn.close().
• test_param_describe_through_python_tcp_forwarder_does_not_deadlock
  exercises a parametrized SELECT with a None argument (forces
  SQLDescribeParam), plus Connection.getinfo(SQL_DBMS_NAME) and
  conn.autocommit as local sanity probes.

Both tests reliably hang to the 30s watchdog timeout without the C++
changes and pass in <1s with them. Full pytest suite: 1767 passed,
58 skipped, 0 failed (~114s).

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 93%

🎯 Overall Coverage 80%

📈 Total Lines Covered: 6664 out of 8273 📁 Project: mssql-python

---

Diff Coverage

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

• mssql_python/pybind/ddbc_bindings.cpp (93.8%): Missing lines 1406-1407

Summary

• Total: 32 lines
• Missing: 2 lines
• Coverage: 93%

mssql_python/pybind/ddbc_bindings.cpp

Lines 1402-1411

  1402         // interpreter is not finalizing - gil_scoped_release is unsafe during
  1403         // shutdown even if PyGILState_Check() reports the GIL as held.
  1404         if (!pythonShuttingDown && PyGILState_Check()) {
  1405             py::gil_scoped_release release;
! 1406             SQLFreeHandle_ptr(_type, _handle);
! 1407         } else {
  1408             SQLFreeHandle_ptr(_type, _handle);
  1409         }
  1410         _handle = nullptr;
  1411     }

---

---

📋 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.7%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.pybind.ddbc_bindings.cpp: 76.2%
mssql_python.row.py: 76.9%
mssql_python.__init__.py: 77.3%
mssql_python.pybind.connection.connection.cpp: 77.3%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.logging.py: 85.5%
mssql_python.connection.py: 85.6%

---

🔗 Quick Links

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