FIX: Cursor.description returns dual-compatible SqlTypeCode type codes by dlevy-msft-sql · Pull Request #355 · microsoft/mssql-python

dlevy-msft-sql · 2025-12-01T17:19:35Z

Work Item / Issue Reference

GitHub Issue: #352

Summary

Fixes cursor.description to return SqlTypeCode instances as type codes instead of raw Python types. SqlTypeCode is dual-compatible: it compares equal to both SQL integer type codes (DB-API 2.0) and Python types (pandas/polars compatibility), so existing code continues to work unchanged.

The original issue was reported when polars pl.read_database() failed with:

ComputeError: could not append value: 2013-01-01 of type: date to the builder

Core change — SqlTypeCode class (type_code.py):

SqlTypeCode wraps an ODBC integer type code with .name and .python_type attributes
__eq__ matches both int values and Python type objects, so desc[1] == str and desc[1] == -9 both work
__int__ returns the raw SQL type code for DB-API 2.0 consumers
Intentionally unhashable (__hash__ raises TypeError) because equality spans multiple hash domains — error message guides users to int(type_code) for dict keys

Cursor internals:

_column_metadata stores per-column (col_name, sql_type, col_size, precision, nullable) tuples from DDBCSQLDescribeCol
_build_converter_map refactored to use stored metadata instead of re-querying
_initialize_description builds SqlTypeCode from stored metadata

Constants and C++ bindings:

Added SQL_SS_TIME2, SQL_SS_UDT, SQL_SS_XML constants
Added #define guards in ddbc_bindings.cpp for SQL_DATETIME2 and SQL_SMALLDATETIME

Converter API:

add_output_converter, get_output_converter, remove_output_converter in connection.py accept Union[int, SqlTypeCode, type]
Uses isinstance(sqltype, SqlTypeCode) to unwrap to .type_code before forwarding to native layer

Testing:

18 new SqlTypeCode unit tests (equality, hashing, repr, pandas compatibility)
Cursor description tests rewritten with SqlTypeCode-aware assertions
New tests: datetime type verification, metadata thread safety, sequential isolation
New test_018_polars_integration.py with 5 integration tests (basic types, dates, nulls, large results, all common types)

Files Changed

File	Changes
`mssql_python/type_code.py`	NEW: `SqlTypeCode` class extracted to own module
`mssql_python/cursor.py`	`_column_metadata` tracking, `_build_converter_map` refactor, `SqlTypeCode` integration
`mssql_python/connection.py`	Converter methods accept `SqlTypeCode` via `isinstance`
`mssql_python/constants.py`	+3 constants (`SQL_SS_TIME2`, `SQL_SS_UDT`, `SQL_SS_XML`)
`mssql_python/pybind/ddbc_bindings.cpp`	+3 `#define` guards
`mssql_python/__init__.py`	Export `SqlTypeCode`
`mssql_python/mssql_python.pyi`	Type stub for `SqlTypeCode`
`CHANGELOG.md`	#352 entries
`tests/test_002_types.py`	18 new `SqlTypeCode` tests
`tests/test_004_cursor.py`	Rewritten description tests, new metadata tests
`tests/test_018_polars_integration.py`	NEW: 5 polars integration tests

Breaking Changes

None. Full backward compatibility maintained:

cursor.description[i][1] == str still works (Python type comparison)
cursor.description[i][1] == -9 also works (SQL type code comparison)
int(cursor.description[i][1]) returns the raw SQL integer type code

Copilot

Pull request overview

This PR fixes issue #352 by implementing two main improvements: (1) correcting cursor.description to return SQL type codes (integers) instead of Python type objects, ensuring DB-API 2.0 specification compliance, and (2) adding support for SQL Server spatial data types (geography, geometry, hierarchyid) by handling the SQL_SS_UDT type code (-151).

Key changes:

Fixed cursor.description[i][1] to return SQL type integer codes (e.g., 4, -9) instead of Python types (int, str) per DB-API 2.0 spec
Added SQL_SS_UDT (-151) support for SQL Server User-Defined Types including spatial data types
Updated output converter lookup to use SQL type codes consistently throughout the codebase

Reviewed changes

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

Show a summary per file

File	Description
mssql_python/cursor.py	Changed `cursor.description` to return SQL type codes instead of Python types; added `_column_metadata` storage; updated `_build_converter_map` to use SQL type codes; added mappings for UDT, XML, DATETIME2, SMALLDATETIME types
mssql_python/constants.py	Added `SQL_SS_UDT = -151` constant for SQL Server User-Defined Types
mssql_python/pybind/ddbc_bindings.cpp	Added C++ constants for SQL_SS_UDT, SQL_DATETIME2, SQL_SMALLDATETIME; implemented UDT handling in SQLGetData_wrap, FetchBatchData, FetchMany_wrap, and FetchAll_wrap for LOB streaming
tests/test_004_cursor.py	Added `lob_wvarchar_column` to test schema; updated `test_cursor_description` to expect SQL type codes; added comprehensive geography type test suite (14 new tests); separated LOB and non-LOB fetch tests; fixed output converter test for UTF-16LE encoding
tests/test_003_connection.py	Simplified converter integration tests to use SQL type constants directly instead of dynamic type detection

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

tests/test_004_cursor.py

mssql_python/constants.py

mssql_python/cursor.py

github-actions · 2026-01-05T19:27:13Z

📊 Code Coverage Report

🔥 Diff Coverage 92%	🎯 Overall Coverage 76%	📈 Total Lines Covered: `5537` out of `7194` 📁 Project: `mssql-python`

Diff Coverage

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

mssql_python/init.py (100%)
mssql_python/connection.py (94.1%): Missing lines 1007
mssql_python/constants.py (100%)
mssql_python/cursor.py (87.0%): Missing lines 1019,1366,2434
mssql_python/type_code.py (93.9%): Missing lines 91,115

Summary

Total: 77 lines
Missing: 6 lines
Coverage: 92%

mssql_python/connection.py

Lines 1003-1011

mssql_python/cursor.py

Lines 1015-1023

Lines 1362-1370

Lines 2430-2438

mssql_python/type_code.py

Lines 87-95

Lines 111-116

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.logger_bridge.hpp: 58.8%
mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.pybind.ddbc_bindings.cpp: 69.3%
mssql_python.pybind.ddbc_bindings.h: 69.7%
mssql_python.pybind.connection.connection.cpp: 75.3%
mssql_python.row.py: 79.5%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.pybind.connection.connection_pool.cpp: 79.6%
mssql_python.connection.py: 84.2%
mssql_python.cursor.py: 84.9%

🔗 Quick Links

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

mssql_python/cursor.py

Copilot

Pull request overview

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

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

mssql_python/cursor.py

tests/test_004_cursor.py

Copilot

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated no new comments.

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

Copilot

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated no new comments.

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

mssql_python/cursor.py

Copilot

Pull request overview

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

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

mssql_python/pybind/ddbc_bindings.cpp

mssql_python/cursor.py

mssql_python/constants.py

- Add SQL_SS_XML (-152) constant to Python constants.py (was incorrectly using SQL_XML = 241) - Add SQL_SS_TIME2 (-154) constant for SQL Server TIME(n) type - Update cursor type map to use SQL_SS_XML and add SQL_SS_TIME2 mapping - Add sync comment in C++ to prevent future constant drift Constants verified against Microsoft Learn ODBC documentation: - SQL_SS_TIME2: -154 (SQLNCLI.h) - SQL_SS_TIMESTAMPOFFSET: -155 (SQLNCLI.h) - SQL_SS_XML: -152 (SQL Server ODBC driver) - SQL_SS_UDT: -151 (SQL Server ODBC driver) Addresses Copilot review feedback on PR microsoft#355

Copilot

Pull request overview

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

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

mssql_python/cursor.py

mssql_python/mssql_python.pyi

mssql_python/cursor.py

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

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

tests/test_018_polars_integration.py

Copilot

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

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

mssql_python/cursor.py

…orkaround

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

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

Copilot · 2026-02-08T01:38:37Z

mssql_python/type_code.py

+    def __eq__(self, other):
+        """Compare equal to both Python types and SQL integer codes."""
+        if isinstance(other, type):
+            return self.python_type == other
+        if isinstance(other, int):


SqlTypeCode.__eq__ only guarantees SqlTypeCode(x) == x, but the reverse (x == SqlTypeCode(x)) will typically be False because int.__eq__ doesn’t defer to the RHS. This also breaks common patterns like type_code in (SQL_WVARCHAR, SQL_VARCHAR) (membership compares int == SqlTypeCode). If the goal is “dual-compatible” with integer codes, consider making SqlTypeCode an int subclass (via __new__) and layering the Python-type comparison on top; also be careful that bool is an int (so SqlTypeCode(1) == True would currently be True).

Copilot · 2026-02-08T01:38:37Z

mssql_python/connection.py

+        if isinstance(sqltype, SqlTypeCode):
+            sqltype = sqltype.type_code
        with self._converters_lock:
            if sqltype in self._output_converters:
                del self._output_converters[sqltype]
                # Pass to the underlying connection if native implementation supports it


remove_output_converter() unwraps SqlTypeCode to its integer code, but doesn’t remove a converter that was registered under the corresponding Python type key (e.g., add_output_converter(str, fn) then remove_output_converter(desc[i][1])). Since get_output_converter() includes a Python-type fallback for SqlTypeCode, removal should be symmetric—consider deleting both keys when a SqlTypeCode is provided.

Copilot · 2026-02-08T01:38:38Z

mssql_python/pybind/ddbc_bindings.cpp

 #define SQL_SS_XML (-152)
+#define SQL_SS_UDT (-151)  // SQL Server User-Defined Types (geometry, geography, hierarchyid)
+#ifndef SQL_DATETIME2
+#define SQL_DATETIME2 (42)
+#endif


SQL_SS_UDT is defined unconditionally; if the build environment’s ODBC headers already define it, this can cause macro redefinition warnings/errors. Mirror the SQL_DATETIME2 / SQL_SMALLDATETIME pattern by wrapping the SQL_SS_UDT define in an #ifndef SQL_SS_UDT guard (same applies to any other SQL Server-specific defines added here).

Copilot · 2026-02-08T01:38:38Z

mssql_python/cursor.py

+        # If all entries are None, return None so that Row can fall back to the
+        # non-optimized path, preserving legacy behavior and fallbacks.
+        if not any(converter_map):
+            return None
+


In _build_converter_map, returning None when all entries are None forces Row to fall back to the legacy per-cell lookup path (because converter_map is falsy), which adds unnecessary get_output_converter() calls for every row/column when converters are registered but don’t apply to this result set. Prefer returning the full converter_map list (even if it’s all None) or adjust Row to distinguish between “no optimized map” vs “optimized map with no converters” (e.g., check converter_map is not None).

Suggested change

# If all entries are None, return None so that Row can fall back to the

# non-optimized path, preserving legacy behavior and fallbacks.

if not any(converter_map):

return None

# Always return the constructed converter_map list, even if all entries are None.

# This allows callers to distinguish between "no optimized map" (None) and

# "optimized map present but no converters apply" (list of Nones), avoiding

# unnecessary fallback to legacy per-cell lookup paths.

Copilot · 2026-02-08T01:38:38Z

mssql_python/type_code.py

+    def __hash__(self):
+        """
+        SqlTypeCode is intentionally unhashable because __eq__ allows
+        comparisons to both Python types and integer SQL codes, and
+        there is no single hash value that can be consistent with both.
+        """
+        raise TypeError(
+            "SqlTypeCode is unhashable. Use int(type_code) or type_code.type_code "
+            "as a dict key instead. Example: {int(desc[1]): handler}"
+        )


This method always raises TypeError - use hash = None instead.

Suggested change

def __hash__(self):

"""

SqlTypeCode is intentionally unhashable because __eq__ allows

comparisons to both Python types and integer SQL codes, and

there is no single hash value that can be consistent with both.

"""

raise TypeError(

"SqlTypeCode is unhashable. Use int(type_code) or type_code.type_code "

"as a dict key instead. Example: {int(desc[1]): handler}"

)

# Intentionally unhashable: __eq__ supports comparison to both Python types

# and integer SQL codes, so there is no single hash value that can remain

# consistent with all equality semantics. Use int(type_code) or

# type_code.type_code as a dict key instead (for example: {int(desc[1]): handler}).

__hash__ = None

Copilot AI review requested due to automatic review settings December 1, 2025 17:19

Copilot started reviewing on behalf of dlevy-msft-sql December 1, 2025 17:20 View session

Copilot finished reviewing on behalf of dlevy-msft-sql December 1, 2025 17:23

Copilot AI reviewed Dec 1, 2025

View reviewed changes

tests/test_004_cursor.py Outdated Show resolved Hide resolved

tests/test_004_cursor.py Outdated Show resolved Hide resolved

mssql_python/constants.py Outdated Show resolved Hide resolved

mssql_python/cursor.py Outdated Show resolved Hide resolved

dlevy-msft-sql added bug Something isn't working pr-size: medium Moderate update size labels Dec 1, 2025

dlevy-msft-sql force-pushed the Issue-352 branch from 3f52dd7 to 646ef04 Compare December 9, 2025 20:56

dlevy-msft-sql added pr-size: small Minimal code update pr-size: medium Moderate update size and removed pr-size: medium Moderate update size labels Jan 16, 2026

sumitmsft reviewed Jan 19, 2026

View reviewed changes

mssql_python/cursor.py Outdated Show resolved Hide resolved

sumitmsft reviewed Jan 19, 2026

View reviewed changes

mssql_python/cursor.py Outdated Show resolved Hide resolved

sumitmsft reviewed Jan 19, 2026

View reviewed changes

mssql_python/cursor.py Show resolved Hide resolved

dlevy-msft-sql requested a review from Copilot January 19, 2026 19:48

Copilot started reviewing on behalf of dlevy-msft-sql January 19, 2026 19:48 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

dlevy-msft-sql requested a review from Copilot January 19, 2026 20:10

Copilot started reviewing on behalf of dlevy-msft-sql January 19, 2026 20:10 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

dlevy-msft-sql requested a review from Copilot January 19, 2026 20:18

Copilot started reviewing on behalf of dlevy-msft-sql January 19, 2026 20:18 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

dlevy-msft-sql linked an issue Jan 19, 2026 that may be closed by this pull request

Cursor.description returning incorrect values #352

Open

sumitmsft reviewed Jan 20, 2026

View reviewed changes

mssql_python/cursor.py Outdated Show resolved Hide resolved

dlevy-msft-sql requested a review from Copilot January 20, 2026 05:13

Copilot started reviewing on behalf of dlevy-msft-sql January 20, 2026 05:13 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

mssql_python/pybind/ddbc_bindings.cpp Show resolved Hide resolved

mssql_python/cursor.py Outdated Show resolved Hide resolved

mssql_python/constants.py Show resolved Hide resolved

dlevy-msft-sql requested a review from Copilot January 20, 2026 05:38

dlevy-msft-sql marked this pull request as draft February 3, 2026 01:42

dlevy-msft-sql requested a review from Copilot February 3, 2026 01:44

Copilot started reviewing on behalf of dlevy-msft-sql February 3, 2026 01:44 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes

mssql_python/cursor.py Outdated Show resolved Hide resolved

mssql_python/mssql_python.pyi Outdated Show resolved Hide resolved

mssql_python/cursor.py Outdated Show resolved Hide resolved

dlevy-msft-sql requested a review from Copilot February 3, 2026 02:17

Copilot AI reviewed Feb 3, 2026

View reviewed changes

dlevy-msft-sql requested a review from Copilot February 3, 2026 02:19

Copilot started reviewing on behalf of dlevy-msft-sql February 3, 2026 02:19 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes

tests/test_018_polars_integration.py Outdated Show resolved Hide resolved

dlevy-msft-sql requested a review from Copilot February 3, 2026 02:33

Copilot started reviewing on behalf of dlevy-msft-sql February 3, 2026 02:33 View session

Copilot AI reviewed Feb 3, 2026

View reviewed changes

mssql_python/cursor.py Outdated Show resolved Hide resolved

dlevy-msft-sql marked this pull request as ready for review February 3, 2026 02:45

saurabh500 previously approved these changes Feb 4, 2026

View reviewed changes

dlevy-msft-sql changed the title ~~FIX: Cursor.describe invalid data~~ fix: cursor.description returns dual-compatible SqlTypeCode type codes Feb 7, 2026

dlevy-msft-sql marked this pull request as draft February 7, 2026 19:46

dlevy-msft-sql changed the title ~~fix: cursor.description returns dual-compatible SqlTypeCode type codes~~ FIX: cursor.description returns dual-compatible SqlTypeCode type codes Feb 7, 2026

dlevy-msft-sql dismissed saurabh500’s stale review via 48a5042 February 7, 2026 19:54

dlevy-msft-sql force-pushed the Issue-352 branch 2 times, most recently from 48a5042 to a61d87e Compare February 7, 2026 20:04

dlevy-msft-sql changed the title ~~FIX: cursor.description returns dual-compatible SqlTypeCode type codes~~ FIX: Cursor.description returns dual-compatible SqlTypeCode type codes Feb 7, 2026

dlevy-msft-sql force-pushed the Issue-352 branch 3 times, most recently from 6002dd0 to f2d2c33 Compare February 7, 2026 20:29

FIX: Extract SqlTypeCode into own module, eliminate circular import w…

e734a2f

…orkaround

dlevy-msft-sql force-pushed the Issue-352 branch from f2d2c33 to e734a2f Compare February 7, 2026 22:03

dlevy-msft-sql marked this pull request as ready for review February 8, 2026 01:14

dlevy-msft-sql requested a review from Copilot February 8, 2026 01:34

Copilot started reviewing on behalf of dlevy-msft-sql February 8, 2026 01:34 View session

Copilot AI reviewed Feb 8, 2026

View reviewed changes

Conversation

dlevy-msft-sql commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Work Item / Issue Reference

Summary

Files Changed

Breaking Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Code Coverage Report

🔥 Diff Coverage

92%

🎯 Overall Coverage

76%

Diff Coverage

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

Summary

mssql_python/connection.py

mssql_python/cursor.py

mssql_python/type_code.py

📋 Files Needing Attention

🔗 Quick Links

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

dlevy-msft-sql commented Dec 1, 2025 •

edited

Loading

github-actions bot commented Jan 5, 2026 •

edited

Loading