FIX: Cursor.describe invalid data #355

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

Work Item / Issue Reference

GitHub Issue: #352

Summary

Add handling for spatial data types and change cursor.describe to return sql type int per dbapi2 spec

…ins an LOB

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

…ins an LOB

…ython into Issue-352

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

📊 Code Coverage Report

🔥 Diff Coverage 98%	🎯 Overall Coverage 76%	📈 Total Lines Covered: `5493` out of `7169` 📁 Project: `mssql-python`

Diff Coverage

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

mssql_python/init.py (100%)
mssql_python/constants.py (100%)
mssql_python/cursor.py (97.4%): Missing lines 128
mssql_python/pybind/ddbc_bindings.cpp (100%)

Summary

Total: 59 lines
Missing: 1 line
Coverage: 98%

mssql_python/cursor.py

Lines 124-132

📋 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.row.py: 66.2%
mssql_python.helpers.py: 67.5%
mssql_python.pybind.ddbc_bindings.cpp: 69.6%
mssql_python.pybind.ddbc_bindings.h: 71.7%
mssql_python.pybind.connection.connection.cpp: 73.6%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.pybind.connection.connection_pool.cpp: 79.6%
mssql_python.connection.py: 84.1%

🔗 Quick Links

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

sumitmsft · 2026-01-19T10:57:33Z

mssql_python/cursor.py

                (
                    column_name,  # name
-                    self._map_data_type(col["DataType"]),  # type_code
+                    col["DataType"],  # type_code (SQL type integer) - CHANGED THIS LINE


While the DB-API 2.0 spec states that type_code "must be one of the Type Objects defined in section 'Type Objects'," it does not strictly mandate using SQL type codes over Python types. Returning SQL type codes is consistent with pyodbc's behavior and is permitted, but not strictly required. We can move ahead with this change. However, this is a breaking change.

Please provide a brief migration guide or example to help users transition (e.g., how to map SQL type codes to Python types if needed).

We need to also put this as a breaking change in our Changelog.

For example, user code like this will break silently:

# Before: worked if cursor.description[0][1] == str: print("String column") # After: fails silently (comparing int to type)

Good catch! I came at it wrong, thinking it was a bug. Updated to make it a non-breaking change.

mssql_python/cursor.py

This PR addresses Issue microsoft#352 by introducing the SQLTypeCode class, which provides backwards compatibility with pandas/polars while also supporting DB-API 2.0 style integer type code comparisons. ## SQLTypeCode Class - New class in cursor.py that wraps SQL type codes - Compares equal to BOTH Python types (str, int, float, etc.) AND SQL integers - Enables: desc[0][1] == str AND desc[0][1] == -9 both returning True - Properties: type_code (int), python_type (type) per DB-API 2.0 spec - Exported from mssql_python public API ## Spatial Data Type Support (SQL_SS_UDT) - Added SQL_SS_UDT (-151) handling in ddbc_bindings.cpp - Fixes fetchall() for geography, geometry, and hierarchyid columns - Binds as binary data and processes correctly ## Code Review Feedback Addressed - Removed unused 'import xml' from cursor.py - Added self._column_metadata = None in Cursor.close() - Type stubs updated to match implementation ## Tests Added (36 new tests) - 18 SQLTypeCode unit tests in test_002_types.py - 8 geometry live database tests in test_004_cursor.py - 8 hierarchyid live database tests in test_004_cursor.py - 2 updated cursor.description compatibility tests ## Documentation - Updated CHANGELOG.md with usage examples - Updated type stubs (mssql_python.pyi) - Wiki update docs prepared in docs/wiki-updates/ Fixes microsoft#352

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

- Remove unused 're' import from test_004_cursor.py - Change bare 'except:' to 'except Exception:' with explanatory comment - Expand destructor docstring with detailed error handling documentation - Clarify UTF-16LE encoding comment for output converter test

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.

dlevy-msft-sql added 4 commits November 24, 2025 20:05

Fix for FetchMany(number of rows) ignores batch size when table conta…

c403899

…ins an LOB

First round of code review fixes

f96d14c

Fix test_fetchone

e135e40

Fix for issue 352

38966d0

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 added 6 commits December 1, 2025 11:31

Apply fixes from copilot review

3f52dd7

Fix for FetchMany(number of rows) ignores batch size when table conta…

38b041b

…ins an LOB

First round of code review fixes

139994a

Fix test_fetchone

6fd823e

Fix for issue 352

a7d9b8e

Apply fixes from copilot review

646ef04

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

dlevy-msft-sql added 2 commits January 5, 2026 13:01

Merge branch 'Issue-352' of https://github.com/dlevy-msft-sql/mssql-p…

8018872

…ython into Issue-352

Merge branch 'main' into Issue-352

67268e5

dlevy-msft-sql added 4 commits January 7, 2026 22:49

Merge branch 'main' into Issue-352

d335ed0

Merge branch 'main' into Issue-352

2dc93f3

Merge branch 'main' into Issue-352

eee5256

Merge branch 'microsoft:main' into Issue-352

d289a9b

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 Show resolved Hide resolved

dlevy-msft-sql added 7 commits January 19, 2026 11:31

fix: Remove stray comment from constants.py

0568451

chore: Update black target-version to include py312, py313

257f0f6

style: Apply black 26.1.0 formatting and pin version in requirements.txt

033f7cd

test: Improve SQLTypeCode equality test for 100% coverage

63c08f5

chore: Remove unnecessary .gitattributes

6adeead

chore: Keep black unpinned to always use latest

7b6da4e

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

refactor: Use DROP TABLE IF EXISTS for cleaner test cleanup

31a6d13

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

FIX: Cursor.describe invalid data #355

Are you sure you want to change the base?

FIX: Cursor.describe invalid data #355

Conversation

dlevy-msft-sql commented Dec 1, 2025

Work Item / Issue Reference

Summary

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

98%

🎯 Overall Coverage

76%

Diff Coverage

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

Summary

mssql_python/cursor.py

📋 Files Needing Attention

🔗 Quick Links

Uh oh!

sumitmsft Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlevy-msft-sql Jan 19, 2026

Choose a reason for hiding this comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Jan 5, 2026 •

edited

Loading

sumitmsft Jan 19, 2026 •

edited

Loading