sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/adapters/oracledb/config.py

@@ -3,11 +3,12 @@
 import contextlib
 import logging
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, TypedDict, Union, cast
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
 
 import oracledb
 from typing_extensions import NotRequired
 
+from sqlspec.adapters.oracledb._numpy_handlers import register_numpy_handlers
 from sqlspec.adapters.oracledb._types import (
     OracleAsyncConnection,
     OracleAsyncConnectionPool,
@@ -23,6 +24,7 @@ from sqlspec.adapters.oracledb.driver import (
 )
 from sqlspec.adapters.oracledb.migrations import OracleAsyncMigrationTracker, OracleSyncMigrationTracker
 from sqlspec.config import AsyncDatabaseConfig, SyncDatabaseConfig
+from sqlspec.typing import NUMPY_INSTALLED
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Callable, Generator
@@ -32,12 +34,18 @@ if TYPE_CHECKING:
     from sqlspec.core.statement import StatementConfig
 
 
-__all__ = ("OracleAsyncConfig", "OracleConnectionParams", "OraclePoolParams", "OracleSyncConfig")
+__all__ = (
+    "OracleAsyncConfig",
+    "OracleConnectionParams",
+    "OracleDriverFeatures",
+    "OraclePoolParams",
+    "OracleSyncConfig",
+)
 
 logger = logging.getLogger(__name__)
 
 
-class OracleConnectionParams(TypedDict, total=False):
+class OracleConnectionParams(TypedDict):
     """OracleDB connection parameters."""
 
     dsn: NotRequired[str]
@@ -58,7 +66,7 @@ class OracleConnectionParams(TypedDict, total=False):
     edition: NotRequired[str]
 
 
-class OraclePoolParams(OracleConnectionParams, total=False):
+class OraclePoolParams(OracleConnectionParams):
     """OracleDB pool parameters."""
 
     min: NotRequired[int]
@@ -77,6 +85,23 @@ class OraclePoolParams(OracleConnectionParams, total=False):
     extra: NotRequired[dict[str, Any]]
 
 
+class OracleDriverFeatures(TypedDict):
+    """Oracle driver feature flags.
+
+    enable_numpy_vectors: Enable automatic NumPy array ↔ Oracle VECTOR conversion.
+        Requires NumPy and Oracle Database 23ai or higher with VECTOR data type support.
+        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]):
     """Configuration for Oracle synchronous database connections."""
 
@@ -85,24 +110,29 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
     driver_type: ClassVar[type[OracleSyncDriver]] = OracleSyncDriver
     connection_type: "ClassVar[type[OracleSyncConnection]]" = OracleSyncConnection
     migration_tracker_type: "ClassVar[type[OracleSyncMigrationTracker]]" = OracleSyncMigrationTracker
+    supports_transactional_ddl: ClassVar[bool] = False
 
     def __init__(
         self,
         *,
-        pool_config: "Optional[Union[OraclePoolParams, dict[str, Any]]]" = None,
-        pool_instance: "Optional[OracleSyncConnectionPool]" = None,
-        migration_config: Optional[dict[str, Any]] = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        pool_config: "OraclePoolParams | dict[str, Any] | None" = None,
+        pool_instance: "OracleSyncConnectionPool | None" = None,
+        migration_config: dict[str, Any] | None = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "OracleDriverFeatures | dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
         """Initialize Oracle synchronous configuration.
 
         Args:
-            pool_config: Pool configuration parameters
-            pool_instance: Existing pool instance to use
-            migration_config: Migration configuration
-            statement_config: Default SQL statement configuration
-            driver_features: Optional driver feature configuration
+            pool_config: Pool configuration parameters.
+            pool_instance: Existing pool instance to use.
+            migration_config: Migration configuration.
+            statement_config: Default SQL statement configuration.
+            driver_features: Optional driver feature configuration (TypedDict or dict).
+            bind_key: Optional unique identifier for this configuration.
+            extension_config: Extension-specific configuration (e.g., Litestar plugin settings).
         """
 
         processed_pool_config: dict[str, Any] = dict(pool_config) if pool_config else {}
@@ -110,18 +140,43 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
             extras = processed_pool_config.pop("extra")
             processed_pool_config.update(extras)
         statement_config = statement_config or oracledb_statement_config
+
+        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,
             pool_instance=pool_instance,
             migration_config=migration_config,
             statement_config=statement_config,
-            driver_features=driver_features or {},
+            driver_features=processed_driver_features,
+            bind_key=bind_key,
+            extension_config=extension_config,
         )
 
     def _create_pool(self) -> "OracleSyncConnectionPool":
         """Create the actual connection pool."""
+        config = dict(self.pool_config)
+
+        if self.driver_features.get("enable_numpy_vectors", False):
+            config["session_callback"] = self._init_connection
 
-        return oracledb.create_pool(**dict(self.pool_config))
+        return oracledb.create_pool(**config)
+
+    def _init_connection(self, connection: "OracleSyncConnection", tag: str) -> None:
+        """Initialize connection with optional NumPy vector support.
+
+        Args:
+            connection: Oracle connection to initialize.
+            tag: Connection tag for session state (unused).
+        """
+        if self.driver_features.get("enable_numpy_vectors", False):
+            from sqlspec.adapters.oracledb._numpy_handlers import register_numpy_handlers
+
+            register_numpy_handlers(connection)
 
     def _close_pool(self) -> None:
         """Close the actual connection pool."""
@@ -155,7 +210,7 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
 
     @contextlib.contextmanager
     def provide_session(
-        self, *args: Any, statement_config: "Optional[StatementConfig]" = None, **kwargs: Any
+        self, *args: Any, statement_config: "StatementConfig | None" = None, **kwargs: Any
     ) -> "Generator[OracleSyncDriver, None, None]":
         """Provide a driver session context manager.
 
@@ -169,7 +224,11 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
         """
         _ = (args, kwargs)  # Mark as intentionally unused
         with self.provide_connection() as conn:
-            yield self.driver_type(connection=conn, statement_config=statement_config or self.statement_config)
+            yield self.driver_type(
+                connection=conn,
+                statement_config=statement_config or self.statement_config,
+                driver_features=self.driver_features,
+            )
 
     def provide_pool(self) -> "OracleSyncConnectionPool":
         """Provide pool instance.
@@ -211,24 +270,29 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
     connection_type: "ClassVar[type[OracleAsyncConnection]]" = OracleAsyncConnection
     driver_type: ClassVar[type[OracleAsyncDriver]] = OracleAsyncDriver
     migration_tracker_type: "ClassVar[type[OracleAsyncMigrationTracker]]" = OracleAsyncMigrationTracker
+    supports_transactional_ddl: ClassVar[bool] = False
 
     def __init__(
         self,
         *,
-        pool_config: "Optional[Union[OraclePoolParams, dict[str, Any]]]" = None,
-        pool_instance: "Optional[OracleAsyncConnectionPool]" = None,
-        migration_config: Optional[dict[str, Any]] = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        pool_config: "OraclePoolParams | dict[str, Any] | None" = None,
+        pool_instance: "OracleAsyncConnectionPool | None" = None,
+        migration_config: dict[str, Any] | None = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "OracleDriverFeatures | dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
         """Initialize Oracle asynchronous configuration.
 
         Args:
-            pool_config: Pool configuration parameters
-            pool_instance: Existing pool instance to use
-            migration_config: Migration configuration
-            statement_config: Default SQL statement configuration
-            driver_features: Optional driver feature configuration
+            pool_config: Pool configuration parameters.
+            pool_instance: Existing pool instance to use.
+            migration_config: Migration configuration.
+            statement_config: Default SQL statement configuration.
+            driver_features: Optional driver feature configuration (TypedDict or dict).
+            bind_key: Optional unique identifier for this configuration.
+            extension_config: Extension-specific configuration (e.g., Litestar plugin settings).
         """
 
         processed_pool_config: dict[str, Any] = dict(pool_config) if pool_config else {}
@@ -236,18 +300,40 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
             extras = processed_pool_config.pop("extra")
             processed_pool_config.update(extras)
 
+        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,
             pool_instance=pool_instance,
             migration_config=migration_config,
             statement_config=statement_config or oracledb_statement_config,
-            driver_features=driver_features or {},
+            driver_features=processed_driver_features,
+            bind_key=bind_key,
+            extension_config=extension_config,
         )
 
     async def _create_pool(self) -> "OracleAsyncConnectionPool":
         """Create the actual async connection pool."""
+        config = dict(self.pool_config)
+
+        if self.driver_features.get("enable_numpy_vectors", False):
+            config["session_callback"] = self._init_connection
 
-        return oracledb.create_pool_async(**dict(self.pool_config))
+        return oracledb.create_pool_async(**config)
+
+    async def _init_connection(self, connection: "OracleAsyncConnection", tag: str) -> None:
+        """Initialize async connection with optional NumPy vector support.
+
+        Args:
+            connection: Oracle async connection to initialize.
+            tag: Connection tag for session state (unused).
+        """
+        if self.driver_features.get("enable_numpy_vectors", False):
+            register_numpy_handlers(connection)
 
     async def _close_pool(self) -> None:
         """Close the actual async connection pool."""
@@ -285,7 +371,7 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
 
     @asynccontextmanager
     async def provide_session(
-        self, *args: Any, statement_config: "Optional[StatementConfig]" = None, **kwargs: Any
+        self, *args: Any, statement_config: "StatementConfig | None" = None, **kwargs: Any
     ) -> "AsyncGenerator[OracleAsyncDriver, None]":
         """Provide an async driver session context manager.
 
@@ -299,7 +385,11 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
         """
         _ = (args, kwargs)  # Mark as intentionally unused
         async with self.provide_connection() as conn:
-            yield self.driver_type(connection=conn, statement_config=statement_config or self.statement_config)
+            yield self.driver_type(
+                connection=conn,
+                statement_config=statement_config or self.statement_config,
+                driver_features=self.driver_features,
+            )
 
     async def provide_pool(self) -> "OracleAsyncConnectionPool":
         """Provide async pool instance.