sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/adapters/oracledb/driver.py

@@ -2,7 +2,8 @@
 
 import contextlib
 import logging
-from typing import TYPE_CHECKING, Any, Optional
+import re
+from typing import TYPE_CHECKING, Any, Final
 
 import oracledb
 from oracledb import AsyncCursor, Cursor
@@ -12,22 +13,39 @@ from sqlspec.adapters.oracledb.data_dictionary import OracleAsyncDataDictionary,
 from sqlspec.adapters.oracledb.type_converter import OracleTypeConverter
 from sqlspec.core.cache import get_cache_config
 from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
-from sqlspec.core.statement import StatementConfig
+from sqlspec.core.result import create_arrow_result
+from sqlspec.core.statement import SQL, StatementConfig
 from sqlspec.driver import (
     AsyncDataDictionaryBase,
     AsyncDriverAdapterBase,
     SyncDataDictionaryBase,
     SyncDriverAdapterBase,
 )
-from sqlspec.exceptions import SQLParsingError, SQLSpecError
+from sqlspec.exceptions import (
+    CheckViolationError,
+    DatabaseConnectionError,
+    DataError,
+    ForeignKeyViolationError,
+    IntegrityError,
+    NotNullViolationError,
+    OperationalError,
+    SQLParsingError,
+    SQLSpecError,
+    TransactionError,
+    UniqueViolationError,
+)
+from sqlspec.utils.module_loader import ensure_pyarrow
 from sqlspec.utils.serializers import to_json
 
 if TYPE_CHECKING:
     from contextlib import AbstractAsyncContextManager, AbstractContextManager
 
+    from sqlspec.builder import QueryBuilder
+    from sqlspec.core import StatementFilter
     from sqlspec.core.result import SQLResult
-    from sqlspec.core.statement import SQL
+    from sqlspec.core.statement import Statement
     from sqlspec.driver._common import ExecutionResult
+    from sqlspec.typing import StatementParameters
 
 logger = logging.getLogger(__name__)
 
@@ -36,6 +54,9 @@ LARGE_STRING_THRESHOLD = 3000  # Threshold for large string parameters to avoid
 
 _type_converter = OracleTypeConverter()
 
+IMPLICIT_UPPER_COLUMN_PATTERN: Final[re.Pattern[str]] = re.compile(r"^(?!\d)(?:[A-Z0-9_]+)$")
+
+
 __all__ = (
     "OracleAsyncDriver",
     "OracleAsyncExceptionHandler",
@@ -45,6 +66,83 @@ __all__ = (
 )
 
 
+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
+
+
+def _coerce_sync_row_values(row: "tuple[Any, ...]") -> "list[Any]":
+    """Coerce LOB handles to concrete values for synchronous execution.
+
+    Processes each value in the row, reading LOB objects and applying
+    type detection for JSON values stored in CLOBs.
+
+    Args:
+        row: Tuple of column values from database fetch.
+
+    Returns:
+        List of coerced values with LOBs read to strings/bytes.
+    """
+    coerced_values: list[Any] = []
+    for value in row:
+        if hasattr(value, "read"):
+            try:
+                processed_value = value.read()
+            except Exception:
+                coerced_values.append(value)
+                continue
+            if isinstance(processed_value, str):
+                processed_value = _type_converter.convert_if_detected(processed_value)
+            coerced_values.append(processed_value)
+        else:
+            coerced_values.append(value)
+    return coerced_values
+
+
+async def _coerce_async_row_values(row: "tuple[Any, ...]") -> "list[Any]":
+    """Coerce LOB handles to concrete values for asynchronous execution.
+
+    Processes each value in the row, reading LOB objects asynchronously
+    and applying type detection for JSON values stored in CLOBs.
+
+    Args:
+        row: Tuple of column values from database fetch.
+
+    Returns:
+        List of coerced values with LOBs read to strings/bytes.
+    """
+    coerced_values: list[Any] = []
+    for value in row:
+        if hasattr(value, "read"):
+            try:
+                processed_value = await _type_converter.process_lob(value)
+            except Exception:
+                coerced_values.append(value)
+                continue
+            if isinstance(processed_value, str):
+                processed_value = _type_converter.convert_if_detected(processed_value)
+            coerced_values.append(processed_value)
+        else:
+            coerced_values.append(value)
+    return coerced_values
+
+
+ORA_CHECK_CONSTRAINT = 2290
+ORA_INTEGRITY_RANGE_START = 2200
+ORA_INTEGRITY_RANGE_END = 2300
+ORA_PARSING_RANGE_START = 900
+ORA_PARSING_RANGE_END = 1000
+ORA_TABLESPACE_FULL = 1652
+
+
 oracledb_statement_config = StatementConfig(
     dialect="oracle",
     parameter_config=ParameterStyleConfig(
@@ -71,7 +169,7 @@ class OracleSyncCursor:
 
     def __init__(self, connection: OracleSyncConnection) -> None:
         self.connection = connection
-        self.cursor: Optional[Cursor] = None
+        self.cursor: Cursor | None = None
 
     def __enter__(self) -> Cursor:
         self.cursor = self.connection.cursor()
@@ -89,7 +187,7 @@ class OracleAsyncCursor:
 
     def __init__(self, connection: OracleAsyncConnection) -> None:
         self.connection = connection
-        self.cursor: Optional[AsyncCursor] = None
+        self.cursor: AsyncCursor | None = None
 
     async def __aenter__(self) -> AsyncCursor:
         self.cursor = self.connection.cursor()
@@ -105,7 +203,11 @@ class OracleAsyncCursor:
 
 
 class OracleSyncExceptionHandler:
-    """Context manager for handling Oracle database exceptions in synchronous operations."""
+    """Context manager for handling Oracle database exceptions.
+
+    Maps Oracle ORA-XXXXX error codes to specific SQLSpec exceptions
+    for better error handling in application code.
+    """
 
     __slots__ = ()
 
@@ -113,46 +215,101 @@ class OracleSyncExceptionHandler:
         return None
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-        _ = exc_tb  # Mark as intentionally unused
+        _ = exc_tb
         if exc_type is None:
             return
-
-        if issubclass(exc_type, oracledb.IntegrityError):
-            e = exc_val
-            msg = f"Oracle integrity constraint violation: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, oracledb.ProgrammingError):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "syntax" in error_msg or "parse" in error_msg:
-                msg = f"Oracle SQL syntax error: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"Oracle programming error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, oracledb.OperationalError):
-            e = exc_val
-            msg = f"Oracle operational error: {e}"
-            raise SQLSpecError(msg) from e
         if issubclass(exc_type, oracledb.DatabaseError):
-            e = exc_val
-            msg = f"Oracle database error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, oracledb.Error):
-            e = exc_val
-            msg = f"Oracle error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, Exception):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "parse" in error_msg or "syntax" in error_msg:
-                msg = f"SQL parsing failed: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"Unexpected database operation error: {e}"
-            raise SQLSpecError(msg) from e
+            self._map_oracle_exception(exc_val)
+
+    def _map_oracle_exception(self, e: Any) -> None:
+        """Map Oracle exception to SQLSpec exception.
+
+        Args:
+            e: oracledb.DatabaseError instance
+        """
+        error_obj = e.args[0] if e.args else None
+        if not error_obj:
+            self._raise_generic_error(e, None)
+
+        error_code = getattr(error_obj, "code", None)
+
+        if not error_code:
+            self._raise_generic_error(e, None)
+
+        if error_code == 1:
+            self._raise_unique_violation(e, error_code)
+        elif error_code in {2291, 2292}:
+            self._raise_foreign_key_violation(e, error_code)
+        elif error_code == ORA_CHECK_CONSTRAINT:
+            self._raise_check_violation(e, error_code)
+        elif error_code in {1400, 1407}:
+            self._raise_not_null_violation(e, error_code)
+        elif error_code and ORA_INTEGRITY_RANGE_START <= error_code < ORA_INTEGRITY_RANGE_END:
+            self._raise_integrity_error(e, error_code)
+        elif error_code in {1017, 12154, 12541, 12545, 12514, 12505}:
+            self._raise_connection_error(e, error_code)
+        elif error_code in {60, 8176}:
+            self._raise_transaction_error(e, error_code)
+        elif error_code in {1722, 1858, 1840}:
+            self._raise_data_error(e, error_code)
+        elif error_code and ORA_PARSING_RANGE_START <= error_code < ORA_PARSING_RANGE_END:
+            self._raise_parsing_error(e, error_code)
+        elif error_code == ORA_TABLESPACE_FULL:
+            self._raise_operational_error(e, error_code)
+        else:
+            self._raise_generic_error(e, error_code)
+
+    def _raise_unique_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle unique constraint violation [ORA-{code:05d}]: {e}"
+        raise UniqueViolationError(msg) from e
+
+    def _raise_foreign_key_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle foreign key constraint violation [ORA-{code:05d}]: {e}"
+        raise ForeignKeyViolationError(msg) from e
+
+    def _raise_check_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle check constraint violation [ORA-{code:05d}]: {e}"
+        raise CheckViolationError(msg) from e
+
+    def _raise_not_null_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle not-null constraint violation [ORA-{code:05d}]: {e}"
+        raise NotNullViolationError(msg) from e
+
+    def _raise_integrity_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle integrity constraint violation [ORA-{code:05d}]: {e}"
+        raise IntegrityError(msg) from e
+
+    def _raise_parsing_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle SQL syntax error [ORA-{code:05d}]: {e}"
+        raise SQLParsingError(msg) from e
+
+    def _raise_connection_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle connection error [ORA-{code:05d}]: {e}"
+        raise DatabaseConnectionError(msg) from e
+
+    def _raise_transaction_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle transaction error [ORA-{code:05d}]: {e}"
+        raise TransactionError(msg) from e
+
+    def _raise_data_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle data error [ORA-{code:05d}]: {e}"
+        raise DataError(msg) from e
+
+    def _raise_operational_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle operational error [ORA-{code:05d}]: {e}"
+        raise OperationalError(msg) from e
+
+    def _raise_generic_error(self, e: Any, code: "int | None") -> None:
+        msg = f"Oracle database error [ORA-{code:05d}]: {e}" if code else f"Oracle database error: {e}"
+        raise SQLSpecError(msg) from e
 
 
 class OracleAsyncExceptionHandler:
-    """Context manager for handling Oracle database exceptions in asynchronous operations."""
+    """Async context manager for handling Oracle database exceptions.
+
+    Maps Oracle ORA-XXXXX error codes to specific SQLSpec exceptions
+    for better error handling in application code.
+    """
 
     __slots__ = ()
 
@@ -160,42 +317,93 @@ class OracleAsyncExceptionHandler:
         return None
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-        _ = exc_tb  # Mark as intentionally unused
+        _ = exc_tb
         if exc_type is None:
             return
-
-        if issubclass(exc_type, oracledb.IntegrityError):
-            e = exc_val
-            msg = f"Oracle integrity constraint violation: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, oracledb.ProgrammingError):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "syntax" in error_msg or "parse" in error_msg:
-                msg = f"Oracle SQL syntax error: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"Oracle programming error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, oracledb.OperationalError):
-            e = exc_val
-            msg = f"Oracle operational error: {e}"
-            raise SQLSpecError(msg) from e
         if issubclass(exc_type, oracledb.DatabaseError):
-            e = exc_val
-            msg = f"Oracle database error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, oracledb.Error):
-            e = exc_val
-            msg = f"Oracle error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, Exception):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "parse" in error_msg or "syntax" in error_msg:
-                msg = f"SQL parsing failed: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"Unexpected async database operation error: {e}"
-            raise SQLSpecError(msg) from e
+            self._map_oracle_exception(exc_val)
+
+    def _map_oracle_exception(self, e: Any) -> None:
+        """Map Oracle exception to SQLSpec exception.
+
+        Args:
+            e: oracledb.DatabaseError instance
+        """
+        error_obj = e.args[0] if e.args else None
+        if not error_obj:
+            self._raise_generic_error(e, None)
+
+        error_code = getattr(error_obj, "code", None)
+
+        if not error_code:
+            self._raise_generic_error(e, None)
+
+        if error_code == 1:
+            self._raise_unique_violation(e, error_code)
+        elif error_code in {2291, 2292}:
+            self._raise_foreign_key_violation(e, error_code)
+        elif error_code == ORA_CHECK_CONSTRAINT:
+            self._raise_check_violation(e, error_code)
+        elif error_code in {1400, 1407}:
+            self._raise_not_null_violation(e, error_code)
+        elif error_code and ORA_INTEGRITY_RANGE_START <= error_code < ORA_INTEGRITY_RANGE_END:
+            self._raise_integrity_error(e, error_code)
+        elif error_code in {1017, 12154, 12541, 12545, 12514, 12505}:
+            self._raise_connection_error(e, error_code)
+        elif error_code in {60, 8176}:
+            self._raise_transaction_error(e, error_code)
+        elif error_code in {1722, 1858, 1840}:
+            self._raise_data_error(e, error_code)
+        elif error_code and ORA_PARSING_RANGE_START <= error_code < ORA_PARSING_RANGE_END:
+            self._raise_parsing_error(e, error_code)
+        elif error_code == ORA_TABLESPACE_FULL:
+            self._raise_operational_error(e, error_code)
+        else:
+            self._raise_generic_error(e, error_code)
+
+    def _raise_unique_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle unique constraint violation [ORA-{code:05d}]: {e}"
+        raise UniqueViolationError(msg) from e
+
+    def _raise_foreign_key_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle foreign key constraint violation [ORA-{code:05d}]: {e}"
+        raise ForeignKeyViolationError(msg) from e
+
+    def _raise_check_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle check constraint violation [ORA-{code:05d}]: {e}"
+        raise CheckViolationError(msg) from e
+
+    def _raise_not_null_violation(self, e: Any, code: int) -> None:
+        msg = f"Oracle not-null constraint violation [ORA-{code:05d}]: {e}"
+        raise NotNullViolationError(msg) from e
+
+    def _raise_integrity_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle integrity constraint violation [ORA-{code:05d}]: {e}"
+        raise IntegrityError(msg) from e
+
+    def _raise_parsing_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle SQL syntax error [ORA-{code:05d}]: {e}"
+        raise SQLParsingError(msg) from e
+
+    def _raise_connection_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle connection error [ORA-{code:05d}]: {e}"
+        raise DatabaseConnectionError(msg) from e
+
+    def _raise_transaction_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle transaction error [ORA-{code:05d}]: {e}"
+        raise TransactionError(msg) from e
+
+    def _raise_data_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle data error [ORA-{code:05d}]: {e}"
+        raise DataError(msg) from e
+
+    def _raise_operational_error(self, e: Any, code: int) -> None:
+        msg = f"Oracle operational error [ORA-{code:05d}]: {e}"
+        raise OperationalError(msg) from e
+
+    def _raise_generic_error(self, e: Any, code: "int | None") -> None:
+        msg = f"Oracle database error [ORA-{code:05d}]: {e}" if code else f"Oracle database error: {e}"
+        raise SQLSpecError(msg) from e
 
 
 class OracleSyncDriver(SyncDriverAdapterBase):
@@ -211,8 +419,8 @@ class OracleSyncDriver(SyncDriverAdapterBase):
     def __init__(
         self,
         connection: OracleSyncConnection,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
     ) -> None:
         if statement_config is None:
             cache_config = get_cache_config()
@@ -224,7 +432,7 @@ class OracleSyncDriver(SyncDriverAdapterBase):
             )
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
-        self._data_dictionary: Optional[SyncDataDictionaryBase] = None
+        self._data_dictionary: SyncDataDictionaryBase | None = None
 
     def with_cursor(self, connection: OracleSyncConnection) -> OracleSyncCursor:
         """Create context manager for Oracle cursor.
@@ -241,7 +449,7 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         """Handle database-specific exceptions and wrap them appropriately."""
         return OracleSyncExceptionHandler()
 
-    def _try_special_handling(self, cursor: Any, statement: "SQL") -> "Optional[SQLResult]":
+    def _try_special_handling(self, cursor: Any, statement: "SQL") -> "SQLResult | None":
         """Hook for Oracle-specific special operations.
 
         Oracle doesn't have complex special operations like PostgreSQL COPY,
@@ -339,9 +547,10 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         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)) for row in fetched_data]
+            # Oracle returns tuples - convert to consistent dict format after LOB hydration
+            data = [dict(zip(column_names, _coerce_sync_row_values(row), strict=False)) for row in fetched_data]
 
             return self.create_execution_result(
                 cursor, selected_data=data, column_names=column_names, data_row_count=len(data), is_select_result=True
@@ -383,6 +592,94 @@ class OracleSyncDriver(SyncDriverAdapterBase):
             msg = f"Failed to commit Oracle transaction: {e}"
             raise SQLSpecError(msg) from e
 
+    def select_to_arrow(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        return_format: str = "table",
+        native_only: bool = False,
+        batch_size: int | None = None,
+        arrow_schema: Any = None,
+        **kwargs: Any,
+    ) -> "Any":
+        """Execute query and return results as Apache Arrow format using Oracle native support.
+
+        This implementation uses Oracle's native fetch_df_all() method which returns
+        an OracleDataFrame with Arrow PyCapsule interface, providing zero-copy data
+        transfer and 5-10x performance improvement over dict conversion.
+
+        Args:
+            statement: SQL query string, Statement, or QueryBuilder
+            *parameters: Query parameters (same format as execute()/select())
+            statement_config: Optional statement configuration override
+            return_format: "table" for pyarrow.Table (default), "batches" for RecordBatch
+            native_only: If False, use base conversion path instead of native (default: False uses native)
+            batch_size: Rows per batch when using "batches" format
+            arrow_schema: Optional pyarrow.Schema for type casting
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            ArrowResult containing pyarrow.Table or RecordBatch
+
+        Examples:
+            >>> result = driver.select_to_arrow(
+            ...     "SELECT * FROM users WHERE age > :1", (18,)
+            ... )
+            >>> df = result.to_pandas()
+            >>> print(df.head())
+        """
+        # Check pyarrow is available
+        ensure_pyarrow()
+
+        # If native_only=False explicitly passed, use base conversion path
+        if native_only is False:
+            return super().select_to_arrow(
+                statement,
+                *parameters,
+                statement_config=statement_config,
+                return_format=return_format,
+                native_only=native_only,
+                batch_size=batch_size,
+                arrow_schema=arrow_schema,
+                **kwargs,
+            )
+
+        import pyarrow as pa
+
+        # Prepare statement with parameters
+        config = statement_config or self.statement_config
+        prepared_statement = self.prepare_statement(statement, parameters, statement_config=config, kwargs=kwargs)
+        sql, prepared_parameters = self._get_compiled_sql(prepared_statement, config)
+
+        # Use Oracle's native fetch_df_all() for zero-copy Arrow transfer
+        oracle_df = self.connection.fetch_df_all(
+            statement=sql, parameters=prepared_parameters or [], arraysize=batch_size or 1000
+        )
+
+        # Convert OracleDataFrame to PyArrow Table using PyCapsule interface
+        arrow_table = pa.table(oracle_df)
+
+        # Apply schema casting if provided
+        if arrow_schema is not None:
+            if not isinstance(arrow_schema, pa.Schema):
+                msg = f"arrow_schema must be a pyarrow.Schema, got {type(arrow_schema).__name__}"
+                raise TypeError(msg)
+            arrow_table = arrow_table.cast(arrow_schema)
+
+        # Convert to batches if requested
+        if return_format == "batches":
+            batches = arrow_table.to_batches()
+            arrow_data: Any = batches[0] if batches else pa.RecordBatch.from_pydict({})
+        else:
+            arrow_data = arrow_table
+
+        # Get row count
+        rows_affected = len(arrow_table)
+
+        return create_arrow_result(statement=prepared_statement, data=arrow_data, rows_affected=rows_affected)
+
     @property
     def data_dictionary(self) -> "SyncDataDictionaryBase":
         """Get the data dictionary for this driver.
@@ -408,8 +705,8 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
     def __init__(
         self,
         connection: OracleAsyncConnection,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
     ) -> None:
         if statement_config is None:
             cache_config = get_cache_config()
@@ -421,7 +718,7 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
             )
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
-        self._data_dictionary: Optional[AsyncDataDictionaryBase] = None
+        self._data_dictionary: AsyncDataDictionaryBase | None = None
 
     def with_cursor(self, connection: OracleAsyncConnection) -> OracleAsyncCursor:
         """Create context manager for Oracle cursor.
@@ -438,7 +735,7 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         """Handle database-specific exceptions and wrap them appropriately."""
         return OracleAsyncExceptionHandler()
 
-    async def _try_special_handling(self, cursor: Any, statement: "SQL") -> "Optional[SQLResult]":
+    async def _try_special_handling(self, cursor: Any, statement: "SQL") -> "SQLResult | None":
         """Hook for Oracle-specific special operations.
 
         Oracle doesn't have complex special operations like PostgreSQL COPY,
@@ -531,9 +828,13 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         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)) for row in fetched_data]
+            # Oracle returns tuples - convert to consistent dict format after LOB hydration
+            data = []
+            for row in fetched_data:
+                coerced_row = await _coerce_async_row_values(row)
+                data.append(dict(zip(column_names, coerced_row, strict=False)))
 
             return self.create_execution_result(
                 cursor, selected_data=data, column_names=column_names, data_row_count=len(data), is_select_result=True
@@ -575,6 +876,94 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
             msg = f"Failed to commit Oracle transaction: {e}"
             raise SQLSpecError(msg) from e
 
+    async def select_to_arrow(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        return_format: str = "table",
+        native_only: bool = False,
+        batch_size: int | None = None,
+        arrow_schema: Any = None,
+        **kwargs: Any,
+    ) -> "Any":
+        """Execute query and return results as Apache Arrow format using Oracle native support.
+
+        This implementation uses Oracle's native fetch_df_all() method which returns
+        an OracleDataFrame with Arrow PyCapsule interface, providing zero-copy data
+        transfer and 5-10x performance improvement over dict conversion.
+
+        Args:
+            statement: SQL query string, Statement, or QueryBuilder
+            *parameters: Query parameters (same format as execute()/select())
+            statement_config: Optional statement configuration override
+            return_format: "table" for pyarrow.Table (default), "batches" for RecordBatch
+            native_only: If False, use base conversion path instead of native (default: False uses native)
+            batch_size: Rows per batch when using "batches" format
+            arrow_schema: Optional pyarrow.Schema for type casting
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            ArrowResult containing pyarrow.Table or RecordBatch
+
+        Examples:
+            >>> result = await driver.select_to_arrow(
+            ...     "SELECT * FROM users WHERE age > :1", (18,)
+            ... )
+            >>> df = result.to_pandas()
+            >>> print(df.head())
+        """
+        # Check pyarrow is available
+        ensure_pyarrow()
+
+        # If native_only=False explicitly passed, use base conversion path
+        if native_only is False:
+            return await super().select_to_arrow(
+                statement,
+                *parameters,
+                statement_config=statement_config,
+                return_format=return_format,
+                native_only=native_only,
+                batch_size=batch_size,
+                arrow_schema=arrow_schema,
+                **kwargs,
+            )
+
+        import pyarrow as pa
+
+        # Prepare statement with parameters
+        config = statement_config or self.statement_config
+        prepared_statement = self.prepare_statement(statement, parameters, statement_config=config, kwargs=kwargs)
+        sql, prepared_parameters = self._get_compiled_sql(prepared_statement, config)
+
+        # Use Oracle's native fetch_df_all() for zero-copy Arrow transfer
+        oracle_df = await self.connection.fetch_df_all(
+            statement=sql, parameters=prepared_parameters or [], arraysize=batch_size or 1000
+        )
+
+        # Convert OracleDataFrame to PyArrow Table using PyCapsule interface
+        arrow_table = pa.table(oracle_df)
+
+        # Apply schema casting if provided
+        if arrow_schema is not None:
+            if not isinstance(arrow_schema, pa.Schema):
+                msg = f"arrow_schema must be a pyarrow.Schema, got {type(arrow_schema).__name__}"
+                raise TypeError(msg)
+            arrow_table = arrow_table.cast(arrow_schema)
+
+        # Convert to batches if requested
+        if return_format == "batches":
+            batches = arrow_table.to_batches()
+            arrow_data: Any = batches[0] if batches else pa.RecordBatch.from_pydict({})
+        else:
+            arrow_data = arrow_table
+
+        # Get row count
+        rows_affected = len(arrow_table)
+
+        return create_arrow_result(statement=prepared_statement, data=arrow_data, rows_affected=rows_affected)
+
     @property
     def data_dictionary(self) -> "AsyncDataDictionaryBase":
         """Get the data dictionary for this driver.