sqlspec 0.26.0__py3-none-any.whl → 0.28.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,26 +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,
-        bind_key: "Optional[str]" = 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
-            bind_key: Optional unique identifier for this 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 {}
@@ -112,19 +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."""
@@ -158,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.
 
@@ -172,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.
@@ -214,26 +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,
-        bind_key: "Optional[str]" = 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
-            bind_key: Optional unique identifier for this 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 {}
@@ -241,19 +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."""
@@ -291,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.
 
@@ -305,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.

sqlspec/adapters/oracledb/data_dictionary.py

@@ -3,7 +3,7 @@
 
 import re
 from contextlib import suppress
-from typing import TYPE_CHECKING, Callable, Optional, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from sqlspec.driver import (
     AsyncDataDictionaryBase,
@@ -15,6 +15,8 @@ from sqlspec.driver import (
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from sqlspec.adapters.oracledb.driver import OracleAsyncDriver, OracleSyncDriver
 
 logger = get_logger("adapters.oracledb.data_dictionary")
@@ -35,12 +37,7 @@ class OracleVersionInfo(VersionInfo):
     """Oracle database version information."""
 
     def __init__(
-        self,
-        major: int,
-        minor: int = 0,
-        patch: int = 0,
-        compatible: "Optional[str]" = None,
-        is_autonomous: bool = False,
+        self, major: int, minor: int = 0, patch: int = 0, compatible: "str | None" = None, is_autonomous: bool = False
     ) -> None:
         """Initialize Oracle version info.
 
@@ -56,7 +53,7 @@ class OracleVersionInfo(VersionInfo):
         self.is_autonomous = is_autonomous
 
     @property
-    def compatible_major(self) -> "Optional[int]":
+    def compatible_major(self) -> "int | None":
         """Get major version from compatible parameter."""
         if not self.compatible:
             return None
@@ -109,7 +106,31 @@ class OracleDataDictionaryMixin:
 
     __slots__ = ()
 
-    def _get_oracle_version(self, driver: "OracleAsyncDriver | OracleSyncDriver") -> "Optional[OracleVersionInfo]":
+    def _get_columns_sql(self, table: str, schema: "str | None" = None) -> str:
+        """Get SQL to query column metadata from Oracle data dictionary.
+
+        Uses USER_TAB_COLUMNS which returns column names in UPPERCASE.
+
+        Args:
+            table: Table name to query columns for
+            schema: Schema name (unused for USER_TAB_COLUMNS)
+
+        Returns:
+            SQL string for Oracle's USER_TAB_COLUMNS query
+        """
+        _ = schema
+        return f"""
+            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
+        """
+
+    def _get_oracle_version(self, driver: "OracleAsyncDriver | OracleSyncDriver") -> "OracleVersionInfo | None":
         """Get Oracle database version information.
 
         Args:
@@ -118,7 +139,7 @@ class OracleDataDictionaryMixin:
         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"
@@ -143,7 +164,7 @@ class OracleDataDictionaryMixin:
         logger.debug("Detected Oracle version: %s", version_info)
         return version_info
 
-    def _get_oracle_compatible(self, driver: "OracleAsyncDriver | OracleSyncDriver") -> "Optional[str]":
+    def _get_oracle_compatible(self, driver: "OracleAsyncDriver | OracleSyncDriver") -> "str | None":
         """Get Oracle compatible parameter value.
 
         Args:
@@ -153,14 +174,14 @@ class OracleDataDictionaryMixin:
             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:
             logger.warning("Compatible parameter not found")
             return None
 
-    def _get_oracle_json_type(self, version_info: "Optional[OracleVersionInfo]") -> str:
+    def _get_oracle_json_type(self, version_info: "OracleVersionInfo | None") -> str:
         """Determine the appropriate JSON column type for Oracle.
 
         Args:
@@ -199,10 +220,10 @@ class OracleSyncDataDictionary(OracleDataDictionaryMixin, SyncDataDictionaryBase
         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) -> "Optional[OracleVersionInfo]":
+    def get_version(self, driver: SyncDriverAdapterBase) -> "OracleVersionInfo | None":
         """Get Oracle database version information.
 
         Args:
@@ -275,6 +296,28 @@ class OracleSyncDataDictionary(OracleDataDictionaryMixin, SyncDataDictionaryBase
         }
         return type_map.get(type_category, "VARCHAR2(255)")
 
+    def get_columns(
+        self, driver: SyncDriverAdapterBase, table: str, schema: "str | None" = None
+    ) -> "list[dict[str, Any]]":
+        """Get column information for a table from Oracle data dictionary.
+
+        Args:
+            driver: Database driver instance
+            table: Table name to query columns for
+            schema: Schema name (ignored for USER_TAB_COLUMNS)
+
+        Returns:
+            List of column metadata dictionaries with keys:
+                - 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)
+        result = oracle_driver.execute(self._get_columns_sql(table, schema))
+        return result.get_data()
+
     def list_available_features(self) -> "list[str]":
         """List available Oracle feature flags.
 
@@ -296,7 +339,7 @@ class OracleSyncDataDictionary(OracleDataDictionaryMixin, SyncDataDictionaryBase
 class OracleAsyncDataDictionary(OracleDataDictionaryMixin, AsyncDataDictionaryBase):
     """Oracle-specific async data dictionary."""
 
-    async def get_version(self, driver: AsyncDriverAdapterBase) -> "Optional[OracleVersionInfo]":
+    async def get_version(self, driver: AsyncDriverAdapterBase) -> "OracleVersionInfo | None":
         """Get Oracle database version information.
 
         Args:
@@ -306,7 +349,7 @@ class OracleAsyncDataDictionary(OracleDataDictionaryMixin, AsyncDataDictionaryBa
             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))
@@ -336,7 +379,7 @@ class OracleAsyncDataDictionary(OracleDataDictionaryMixin, AsyncDataDictionaryBa
         logger.debug("Detected Oracle version: %s", version_info)
         return version_info
 
-    async def _get_oracle_compatible_async(self, driver: "OracleAsyncDriver") -> "Optional[str]":
+    async def _get_oracle_compatible_async(self, driver: "OracleAsyncDriver") -> "str | None":
         """Get Oracle compatible parameter value (async version).
 
         Args:
@@ -346,7 +389,9 @@ class OracleAsyncDataDictionary(OracleDataDictionaryMixin, AsyncDataDictionaryBa
             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:
@@ -364,7 +409,7 @@ class OracleAsyncDataDictionary(OracleDataDictionaryMixin, AsyncDataDictionaryBa
         """
         # 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:
@@ -424,6 +469,28 @@ class OracleAsyncDataDictionary(OracleDataDictionaryMixin, AsyncDataDictionaryBa
         type_map = {"uuid": "RAW(16)", "boolean": "NUMBER(1)", "timestamp": "TIMESTAMP", "text": "CLOB", "blob": "BLOB"}
         return type_map.get(type_category, "VARCHAR2(255)")
 
+    async def get_columns(
+        self, driver: AsyncDriverAdapterBase, table: str, schema: "str | None" = None
+    ) -> "list[dict[str, Any]]":
+        """Get column information for a table from Oracle data dictionary.
+
+        Args:
+            driver: Async database driver instance
+            table: Table name to query columns for
+            schema: Schema name (ignored for USER_TAB_COLUMNS)
+
+        Returns:
+            List of column metadata dictionaries with keys:
+                - 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)
+        result = await oracle_driver.execute(self._get_columns_sql(table, schema))
+        return result.get_data()
+
     def list_available_features(self) -> "list[str]":
         """List available Oracle feature flags.