FEAT: Add spatial type support (geography, geometry, hierarchyid) (#423)

### Work Item / Issue Reference

> GitHub Issue #352

-------------------------------------------------------------------
### Summary

Adds `SQL_SS_UDT` (-151) handling so `geography`, `geometry`, and
`hierarchyid` columns are fetched as `bytes` instead of raising errors.
These SQL Server CLR User-Defined Types all report as `SQL_SS_UDT` via
ODBC and were previously unhandled in both the C++ binding layer and
Python type maps.

## Changes

| File | Change |
|------|--------|
| `ddbc_bindings.cpp` | Define `SQL_SS_UDT` constant; add `case
SQL_SS_UDT:` fallthroughs to `SQL_BINARY` in `SQLGetData_wrap`,
`SQLBindColums`, and `FetchBatchData`; separate `calculateRowSize` case
with LOB-size fallback; include in LOB detection for `FetchMany_wrap`
and `FetchAll_wrap` |
| `constants.py` | Add `SQL_SS_UDT = -151` to `ConstantsDDBC` enum and
`get_valid_types()` |
| `cursor.py` | Add `SQL_SS_UDT -> SQL_C_BINARY` in `sql_to_c_type` map;
add `SQL_SS_UDT -> bytes` in `sql_to_python_type` map |
| `test_017_spatial_types.py` | 37 tests covering geography, geometry,
and hierarchyid: fetch paths (fetchone/fetchmany/fetchall/executemany),
NULL handling, mixed columns, binary round-trips, output converters,
cursor.description metadata, error cases |

## Testing

- Built `ddbc_bindings.cp313-arm64.pyd` with 0 errors
- Existing test suite: 639 passed, 1 pre-existing failure (unrelated
`test_no_segfault_on_gc` WinError 50), 8 skipped
- Spatial tests require live SQL Server connection with
geography/geometry/hierarchyid support

Co-authored-by: gargsaumya <saumyagarg.100@gmail.com>

Author: dlevy-msft-sql

mssql_python/constants.py

@@ -114,6 +114,7 @@ class ConstantsDDBC(Enum):
     SQL_FETCH_ABSOLUTE = 5
     SQL_FETCH_RELATIVE = 6
     SQL_FETCH_BOOKMARK = 8
+    SQL_SS_UDT = -151
     SQL_DATETIMEOFFSET = -155
     SQL_SS_TIME2 = -154
     SQL_SS_XML = -152
@@ -374,6 +375,7 @@ def get_valid_types(cls) -> set:
             ConstantsDDBC.SQL_DATETIMEOFFSET.value,
             ConstantsDDBC.SQL_SS_XML.value,
             ConstantsDDBC.SQL_GUID.value,
+            ConstantsDDBC.SQL_SS_UDT.value,
         }
 
     # Could also add category methods for convenience

mssql_python/cursor.py

@@ -865,6 +865,7 @@ def _get_c_type_for_sql_type(self, sql_type: int) -> int:
             ddbc_sql_const.SQL_BINARY.value: ddbc_sql_const.SQL_C_BINARY.value,
             ddbc_sql_const.SQL_VARBINARY.value: ddbc_sql_const.SQL_C_BINARY.value,
             ddbc_sql_const.SQL_LONGVARBINARY.value: ddbc_sql_const.SQL_C_BINARY.value,
+            ddbc_sql_const.SQL_SS_UDT.value: ddbc_sql_const.SQL_C_BINARY.value,
             # ODBC 3.x date/time types (reported by ODBC 18 driver)
             ddbc_sql_const.SQL_TYPE_DATE.value: ddbc_sql_const.SQL_C_TYPE_DATE.value,
             ddbc_sql_const.SQL_TYPE_TIME.value: ddbc_sql_const.SQL_C_TYPE_TIME.value,
@@ -1052,6 +1053,7 @@ def _map_data_type(self, sql_type):
             SQL_SS_TIME2(-154)  for time columns
             SQL_DATETIMEOFFSET(-155)  for datetimeoffset columns
             SQL_SS_XML(-152)  for xml columns
+            SQL_SS_UDT(-151)  for geography/geometry/hierarchyid columns
 
         ODBC 2.x aliases (9, 10, 11) are also accepted defensively.
 
@@ -1097,6 +1099,7 @@ def _map_data_type(self, sql_type):
             ddbc_sql_const.SQL_BINARY.value: bytes,
             ddbc_sql_const.SQL_VARBINARY.value: bytes,
             ddbc_sql_const.SQL_LONGVARBINARY.value: bytes,
+            ddbc_sql_const.SQL_SS_UDT.value: bytes,
             # UUID
             ddbc_sql_const.SQL_GUID.value: uuid.UUID,
             # XML — driver reports SQL_SS_XML (-152), fetched as str

mssql_python/pybind/ddbc_bindings.cpp

@@ -20,13 +20,14 @@
 // Macro definitions
 //-------------------------------------------------------------------------------------------------
 
-// This constant is not exposed via sql.h, hence define it here
+// These constants are not exposed via sql.h, hence define them here
 #define SQL_SS_TIME2 (-154)
 #define SQL_SS_TIMESTAMPOFFSET (-155)
 #define SQL_C_SS_TIMESTAMPOFFSET (0x4001)
 #define MAX_DIGITS_IN_NUMERIC 64
 #define SQL_MAX_NUMERIC_LEN 16
 #define SQL_SS_XML (-152)
+#define SQL_SS_UDT (-151)
 
 #define STRINGIFY_FOR_CASE(x)                                                                      \
     case x:                                                                                        \
@@ -3285,6 +3286,7 @@ SQLRETURN SQLGetData_wrap(SqlHandlePtr StatementHandle, SQLUSMALLINT colCount, p
                 }
                 break;
             }
+            case SQL_SS_UDT:
             case SQL_BINARY:
             case SQL_VARBINARY:
             case SQL_LONGVARBINARY: {
@@ -3555,6 +3557,7 @@ SQLRETURN SQLBindColums(SQLHSTMT hStmt, ColumnBuffers& buffers, py::list& column
                 ret = SQLBindCol_ptr(hStmt, col, SQL_C_GUID, buffers.guidBuffers[col - 1].data(),
                                      sizeof(SQLGUID), buffers.indicators[col - 1].data());
                 break;
+            case SQL_SS_UDT:
             case SQL_BINARY:
             case SQL_VARBINARY:
             case SQL_LONGVARBINARY:
@@ -3683,6 +3686,7 @@ SQLRETURN FetchBatchData(SQLHSTMT hStmt, ColumnBuffers& buffers, py::list& colum
             case SQL_WLONGVARCHAR:
                 columnProcessors[col] = ColumnProcessors::ProcessWChar;
                 break;
+            case SQL_SS_UDT:
             case SQL_BINARY:
             case SQL_VARBINARY:
             case SQL_LONGVARBINARY:
@@ -3981,6 +3985,10 @@ size_t calculateRowSize(py::list& columnNames, SQLUSMALLINT numCols) {
             case SQL_BIT:
                 rowSize += sizeof(SQLCHAR);
                 break;
+            case SQL_SS_UDT:
+                rowSize += (static_cast<SQLLEN>(columnSize) == SQL_NO_TOTAL || columnSize == 0)
+                               ? SQL_MAX_LOB_SIZE : columnSize;
+                break;
             case SQL_BINARY:
             case SQL_VARBINARY:
             case SQL_LONGVARBINARY:
@@ -4043,7 +4051,8 @@ SQLRETURN FetchMany_wrap(SqlHandlePtr StatementHandle, py::list& rows, int fetch
 
         if ((dataType == SQL_WVARCHAR || dataType == SQL_WLONGVARCHAR || dataType == SQL_VARCHAR ||
              dataType == SQL_LONGVARCHAR || dataType == SQL_VARBINARY ||
-             dataType == SQL_LONGVARBINARY || dataType == SQL_SS_XML) &&
+             dataType == SQL_LONGVARBINARY || dataType == SQL_SS_XML ||
+             dataType == SQL_SS_UDT) &&
             (columnSize == 0 || columnSize == SQL_NO_TOTAL || columnSize > SQL_MAX_LOB_SIZE)) {
             lobColumns.push_back(i + 1);  // 1-based
         }
@@ -4181,7 +4190,8 @@ SQLRETURN FetchAll_wrap(SqlHandlePtr StatementHandle, py::list& rows,
 
         if ((dataType == SQL_WVARCHAR || dataType == SQL_WLONGVARCHAR || dataType == SQL_VARCHAR ||
              dataType == SQL_LONGVARCHAR || dataType == SQL_VARBINARY ||
-             dataType == SQL_LONGVARBINARY || dataType == SQL_SS_XML) &&
+             dataType == SQL_LONGVARBINARY || dataType == SQL_SS_XML ||
+             dataType == SQL_SS_UDT) &&
             (columnSize == 0 || columnSize == SQL_NO_TOTAL || columnSize > SQL_MAX_LOB_SIZE)) {
             lobColumns.push_back(i + 1);  // 1-based
         }