feat(oracle): implicitly named columns create lower-case dictionary keys (#139)

Introduce a feature to normalize implicit Oracle uppercase column names to lowercase, enhancing compatibility with schema libraries that expect snake_case fields. This feature is enabled by default and preserves quoted case-sensitive aliases. Tests ensure correct functionality for both enabled and disabled states.

Author: cofin

docs/guides/adapters/oracle.md

@@ -54,7 +54,7 @@ The Oracle session stores (`OracleAsyncStore` and `OracleSyncStore`) support opt
 
 ```python
 from sqlspec.adapters.oracledb import OracleAsyncConfig
-from sqlspec.adapters.oracledb.litestar.store import OracleAsyncStore
+from sqlspec.adapters.oracledb.litestar import OracleAsyncStore
 
 config = OracleAsyncConfig(pool_config={"dsn": "oracle://..."})
 
@@ -102,19 +102,39 @@ If `use_in_memory=True` but In-Memory is not available/licensed, table creation
 
 **Recommendation:** Use `use_in_memory=False` (default) unless you have confirmed licensing and configuration.
 
-### Performance Characteristics
+## Column Name Normalization
 
-**In-Memory Session Store Performance:**
+Oracle returns unquoted identifiers in uppercase (for example `ID`, `PRODUCT_NAME`). When those rows feed into schema libraries that expect snake_case fields, the uppercase keys can trigger validation errors. SQLSpec resolves this automatically through the `enable_lowercase_column_names` driver feature, which is **enabled by default**.
 
-- Read operations: 2-5x faster for single lookups
-- Scan operations: 10-50x faster for bulk operations
-- Write operations: Negligible impact (asynchronous population)
-- Memory usage: ~2-3x table size (dual format storage)
+```python
+from sqlspec.adapters.oracledb import OracleAsyncConfig
 
-**Memory Sizing Example:**
+config = OracleAsyncConfig(
+    pool_config={"dsn": "oracle://..."},
+    driver_features={"enable_lowercase_column_names": True},
+)
+```
 
-- 1M sessions × 5KB avg = ~5GB table size
-- In-Memory requirement: ~10-15GB (with compression)
+### How normalization works
+
+- Identifiers matching Oracle's implicit uppercase pattern (`^(?!\d)(?:[A-Z0-9_]+)$`) are lowercased.
+- Quoted or user-defined aliases (mixed case, symbols, or names beginning with digits) retain their original casing.
+- Disabling the feature restores Oracle's native uppercase behaviour:
+
+```python
+config = OracleAsyncConfig(
+    pool_config={"dsn": "oracle://..."},
+    driver_features={"enable_lowercase_column_names": False},
+)
+```
+
+### When to opt out
+
+- You rely on two columns that differ only by case (for example `ID` and `Id`).
+- You intentionally alias everything in uppercase and want to preserve that style.
+- You prefer to manage casing entirely in SQL using quoted identifiers.
+
+In those scenarios set `enable_lowercase_column_names=False`. Otherwise, keep the default for seamless msgspec/pydantic hydration without extra SQL aliases.
 
 ## NumPy Vector Support (Oracle 23ai+)
 
@@ -283,19 +303,22 @@ await session.execute(
 ### Error Handling
 
 **Unsupported dtype:**
+
 ```python
 vector = np.array([1.0, 2.0], dtype=np.float16)  # Not supported
 # Raises: TypeError: Unsupported NumPy dtype for Oracle VECTOR: float16
 ```
 
 **Dimension mismatch:**
+
 ```python
 vector = np.random.rand(512).astype(np.float32)
 # Trying to insert into VECTOR(768, FLOAT32) column
 # Raises: ORA-51813: Vector dimension count must match
 ```
 
 **NumPy not installed:**
+
 ```python
 # With enable_numpy_vectors=True but NumPy not installed
 # Falls back to array.array (Python stdlib)

sqlspec/adapters/oracledb/config.py

@@ -93,9 +93,13 @@ class OracleDriverFeatures(TypedDict):
         Defaults to True when NumPy is installed.
         Provides automatic bidirectional conversion between NumPy ndarrays and Oracle VECTOR columns.
         Supports float32, float64, int8, and uint8 dtypes.
+    enable_lowercase_column_names: Normalize implicit Oracle uppercase column names to lowercase.
+        Targets unquoted Oracle identifiers that default to uppercase while preserving quoted case-sensitive aliases.
+        Defaults to True for compatibility with schema libraries expecting snake_case fields.
     """
 
     enable_numpy_vectors: NotRequired[bool]
+    enable_lowercase_column_names: NotRequired[bool]
 
 
 class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConnectionPool", OracleSyncDriver]):
@@ -140,6 +144,8 @@ def __init__(
         processed_driver_features: dict[str, Any] = dict(driver_features) if driver_features else {}
         if "enable_numpy_vectors" not in processed_driver_features:
             processed_driver_features["enable_numpy_vectors"] = NUMPY_INSTALLED
+        if "enable_lowercase_column_names" not in processed_driver_features:
+            processed_driver_features["enable_lowercase_column_names"] = True
 
         super().__init__(
             pool_config=processed_pool_config,
@@ -297,6 +303,8 @@ def __init__(
         processed_driver_features: dict[str, Any] = dict(driver_features) if driver_features else {}
         if "enable_numpy_vectors" not in processed_driver_features:
             processed_driver_features["enable_numpy_vectors"] = NUMPY_INSTALLED
+        if "enable_lowercase_column_names" not in processed_driver_features:
+            processed_driver_features["enable_lowercase_column_names"] = True
 
         super().__init__(
             pool_config=processed_pool_config,

sqlspec/adapters/oracledb/data_dictionary.py

@@ -120,7 +120,11 @@ def _get_columns_sql(self, table: str, schema: "str | None" = None) -> str:
         """
         _ = schema
         return f"""
-            SELECT column_name, data_type, data_length, nullable
+            SELECT
+                column_name AS "column_name",
+                data_type AS "data_type",
+                data_length AS "data_length",
+                nullable AS "nullable"
             FROM user_tab_columns
             WHERE table_name = '{table.upper()}'
             ORDER BY column_id
@@ -135,7 +139,7 @@ def _get_oracle_version(self, driver: "OracleAsyncDriver | OracleSyncDriver") ->
         Returns:
             Oracle version information or None if detection fails
         """
-        banner = driver.select_value("SELECT banner FROM v$version WHERE banner LIKE 'Oracle%'")
+        banner = driver.select_value("SELECT banner AS \"banner\" FROM v$version WHERE banner LIKE 'Oracle%'")
 
         # Parse version from banner like "Oracle Database 21c Enterprise Edition Release 21.0.0.0.0 - Production"
         # or "Oracle Database 19c Standard Edition 2 Release 19.0.0.0.0 - Production"
@@ -170,7 +174,7 @@ def _get_oracle_compatible(self, driver: "OracleAsyncDriver | OracleSyncDriver")
             Compatible parameter value or None if detection fails
         """
         try:
-            compatible = driver.select_value("SELECT value FROM v$parameter WHERE name = 'compatible'")
+            compatible = driver.select_value("SELECT value AS \"value\" FROM v$parameter WHERE name = 'compatible'")
             logger.debug("Detected Oracle compatible parameter: %s", compatible)
             return str(compatible)
         except Exception:
@@ -216,7 +220,7 @@ def _is_oracle_autonomous(self, driver: "OracleSyncDriver") -> bool:
         Returns:
             True if this is an Autonomous Database, False otherwise
         """
-        result = driver.select_value_or_none("SELECT COUNT(*) as cnt FROM v$pdbs WHERE cloud_identity IS NOT NULL")
+        result = driver.select_value_or_none('SELECT COUNT(1) AS "cnt" FROM v$pdbs WHERE cloud_identity IS NOT NULL')
         return bool(result and int(result) > 0)
 
     def get_version(self, driver: SyncDriverAdapterBase) -> "OracleVersionInfo | None":
@@ -304,10 +308,10 @@ def get_columns(
 
         Returns:
             List of column metadata dictionaries with keys:
-                - COLUMN_NAME: Name of the column (UPPERCASE in Oracle)
-                - DATA_TYPE: Oracle data type
-                - DATA_LENGTH: Maximum length (for character types)
-                - NULLABLE: 'Y' or 'N'
+                - column_name: Name of the column
+                - data_type: Oracle data type
+                - data_length: Maximum length (for character types)
+                - nullable: 'Y' or 'N'
         """
 
         oracle_driver = cast("OracleSyncDriver", driver)
@@ -345,7 +349,7 @@ async def get_version(self, driver: AsyncDriverAdapterBase) -> "OracleVersionInf
             Oracle version information or None if detection fails
         """
         banner = await cast("OracleAsyncDriver", driver).select_value(
-            "SELECT banner FROM v$version WHERE banner LIKE 'Oracle%'"
+            "SELECT banner AS \"banner\" FROM v$version WHERE banner LIKE 'Oracle%'"
         )
 
         version_match = ORACLE_VERSION_PATTERN.search(str(banner))
@@ -385,7 +389,9 @@ async def _get_oracle_compatible_async(self, driver: "OracleAsyncDriver") -> "st
             Compatible parameter value or None if detection fails
         """
         try:
-            compatible = await driver.select_value("SELECT value FROM v$parameter WHERE name = 'compatible'")
+            compatible = await driver.select_value(
+                "SELECT value AS \"value\" FROM v$parameter WHERE name = 'compatible'"
+            )
             logger.debug("Detected Oracle compatible parameter: %s", compatible)
             return str(compatible)
         except Exception:
@@ -403,7 +409,7 @@ async def _is_oracle_autonomous_async(self, driver: "OracleAsyncDriver") -> bool
         """
         # Check for cloud_identity in v$pdbs (most reliable for Autonomous)
         with suppress(Exception):
-            result = await driver.execute("SELECT COUNT(*) as cnt FROM v$pdbs WHERE cloud_identity IS NOT NULL")
+            result = await driver.execute('SELECT COUNT(1) AS "cnt" FROM v$pdbs WHERE cloud_identity IS NOT NULL')
             if result.data:
                 count = result.data[0]["cnt"] if isinstance(result.data[0], dict) else result.data[0][0]
                 if int(count) > 0:
@@ -475,10 +481,10 @@ async def get_columns(
 
         Returns:
             List of column metadata dictionaries with keys:
-                - COLUMN_NAME: Name of the column (UPPERCASE in Oracle)
-                - DATA_TYPE: Oracle data type
-                - DATA_LENGTH: Maximum length (for character types)
-                - NULLABLE: 'Y' or 'N'
+                - column_name: Name of the column
+                - data_type: Oracle data type
+                - data_length: Maximum length (for character types)
+                - nullable: 'Y' or 'N'
         """
 
         oracle_driver = cast("OracleAsyncDriver", driver)

sqlspec/adapters/oracledb/driver.py

@@ -2,7 +2,8 @@
 
 import contextlib
 import logging
-from typing import TYPE_CHECKING, Any
+import re
+from typing import TYPE_CHECKING, Any, Final
 
 import oracledb
 from oracledb import AsyncCursor, Cursor
@@ -48,6 +49,22 @@
 
 _type_converter = OracleTypeConverter()
 
+IMPLICIT_UPPER_COLUMN_PATTERN: Final[re.Pattern[str]] = re.compile(r"^(?!\d)(?:[A-Z0-9_]+)$")
+
+
+def _normalize_column_names(column_names: "list[str]", driver_features: "dict[str, Any]") -> "list[str]":
+    should_lowercase = driver_features.get("enable_lowercase_column_names", False)
+    if not should_lowercase:
+        return column_names
+    normalized: list[str] = []
+    for name in column_names:
+        if name and IMPLICIT_UPPER_COLUMN_PATTERN.fullmatch(name):
+            normalized.append(name.lower())
+        else:
+            normalized.append(name)
+    return normalized
+
+
 __all__ = (
     "OracleAsyncDriver",
     "OracleAsyncExceptionHandler",
@@ -468,6 +485,7 @@ def _execute_statement(self, cursor: Any, statement: "SQL") -> "ExecutionResult"
         if statement.returns_rows():
             fetched_data = cursor.fetchall()
             column_names = [col[0] for col in cursor.description or []]
+            column_names = _normalize_column_names(column_names, self.driver_features)
 
             # Oracle returns tuples - convert to consistent dict format
             data = [dict(zip(column_names, row, strict=False)) for row in fetched_data]
@@ -660,6 +678,7 @@ async def _execute_statement(self, cursor: Any, statement: "SQL") -> "ExecutionR
         if statement.returns_rows():
             fetched_data = await cursor.fetchall()
             column_names = [col[0] for col in cursor.description or []]
+            column_names = _normalize_column_names(column_names, self.driver_features)
 
             # Oracle returns tuples - convert to consistent dict format
             data = [dict(zip(column_names, row, strict=False)) for row in fetched_data]

sqlspec/adapters/oracledb/migrations.py

@@ -159,7 +159,7 @@ def _migrate_schema_if_needed(self, driver: "SyncDriverAdapterBase") -> None:
         """
         try:
             columns_data = driver.data_dictionary.get_columns(driver, self.version_table)
-            existing_columns = {row["COLUMN_NAME"] for row in columns_data}
+            existing_columns = {str(row["column_name"]).upper() for row in columns_data}
             missing_columns = self._detect_missing_columns(existing_columns)
 
             if not missing_columns:
@@ -353,7 +353,7 @@ async def _migrate_schema_if_needed(self, driver: "AsyncDriverAdapterBase") -> N
         """
         try:
             columns_data = await driver.data_dictionary.get_columns(driver, self.version_table)
-            existing_columns = {row["COLUMN_NAME"] for row in columns_data}
+            existing_columns = {str(row["column_name"]).upper() for row in columns_data}
             missing_columns = self._detect_missing_columns(existing_columns)
 
             if not missing_columns: