FIX: Prevent late Windows ODBC ENV cleanup during shutdown

[Jahnvi Thakkar (jahnvi480)]

Work Item / Issue Reference

AB#48085

---

Summary

Prevent Windows process-exit access violations caused by the static ODBC environment handle calling SQLFreeHandle after Python finalization during DLL teardown.

Extend the existing finalization guard to SQL_HANDLE_ENV on Windows only. Preserve normal-lifetime handle cleanup, existing STMT/DBC protection, implicit-free checks, and GIL-release behavior. Unix ENV cleanup remains unchanged.

Strengthen the existing shutdown tests to verify query results, pooled and nonpooled explicit cleanup, completion of Python cleanup, and actual subprocess exit codes. No new test files, production pipeline changes, or diagnostic infrastructure are included.

The frozen candidate was validated in hosted diagnostic 174475: 700 fresh subprocesses on SQL2022/Python3.13.15 and 700 on SQL2025/Python3.14.7, all exiting successfully without access violations or timeouts on Windows Server2025 x64. Those results apply to the candidate based on 89c22515; normal PR validation of the current-main integration remains pending.

This addresses the demonstrated late-ENV shutdown defect, not every possible Windows access violation.

[Copilot]

🔵 Needs a closer look

The shutdown test must record and validate cleanup results before approval.

Pull request overview

This PR prevents late Windows ODBC environment-handle cleanup during Python shutdown and expands subprocess shutdown testing.

Changes:

• Adds Windows-only ENV cleanup protection.
• Strengthens pooled and nonpooled shutdown coverage.

File summaries

File	Summary
tests/test_013_SqlHandle_free_shutdown.py	Expands shutdown tests, but the completion sentinel does not verify cleanup results or failures.
mssql_python/pybind/ddbc_bindings.cpp	Adds Windows-only protection for late ENV handle cleanup.

Review details

Suppressed comments (1)

tests/test_013_SqlHandle_free_shutdown.py:335

• This sentinel only proves that a later atexit callback was reached. All three connections are already explicitly closed and shutdown_pooling() is called before exit, while _cleanup_connections() catches and suppresses per-connection failures (mssql_python/__init__.py:115-130), so the subprocess can print this success marker even if Python's cleanup did no work or encountered an error. Please make the child record/validate the cleanup result (including a failure marker/nonzero outcome) before asserting completion.

            # Registered before the driver so this runs after its atexit cleanup.
            atexit.register(lambda: print("Python connection and pool cleanup completed"))

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

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

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 100%

🎯 Overall Coverage 83%

📈 Total Lines Covered: 8221 out of 9875 📁 Project: mssql-python

---

Diff Coverage

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

No lines with coverage information in this diff.

---

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.performance_counter.hpp: 0.7%
mssql_python.pybind.logger_bridge.cpp: 57.9%
mssql_python.pybind.ddbc_bindings.h: 61.5%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.row.py: 77.6%
mssql_python.pybind.ddbc_bindings.cpp: 77.7%
mssql_python.pybind.connection.connection_pool.cpp: 81.8%
mssql_python.logging.py: 85.5%
mssql_python.helpers.py: 89.3%
mssql_python.pooling.py: 90.1%

---

🔗 Quick Links

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