sqlspec 0.17.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

sqlspec/adapters/oracledb/driver.py

@@ -121,6 +121,7 @@ class OracleSyncExceptionHandler:
         return None
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        _ = exc_tb  # Mark as intentionally unused
         if exc_type is None:
             return
 
@@ -167,6 +168,7 @@ class OracleAsyncExceptionHandler:
         return None
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        _ = exc_tb  # Mark as intentionally unused
         if exc_type is None:
             return
 
@@ -205,36 +207,10 @@ class OracleAsyncExceptionHandler:
 
 
 class OracleSyncDriver(SyncDriverAdapterBase):
-    """Enhanced Oracle Sync driver with CORE_ROUND_3 architecture integration.
-
-    This sync driver leverages the complete core module system for maximum Oracle performance:
-
-    Performance Improvements:
-    - 5-10x faster SQL compilation through single-pass processing
-    - 40-60% memory reduction through __slots__ optimization
-    - Enhanced caching for repeated statement execution
-    - Zero-copy parameter processing where possible
-    - Sync-optimized resource management
-    - Optimized Oracle parameter style conversion (QMARK -> NAMED_COLON)
-
-    Oracle Features:
-    - Parameter style conversion (QMARK to NAMED_COLON/POSITIONAL_COLON)
-    - Oracle-specific type coercion and data handling
-    - Enhanced error categorization for Oracle database errors
-    - Transaction management with automatic commit/rollback
-    - Oracle-specific data handling and optimization
-
-    Core Integration Features:
-    - sqlspec.core.statement for enhanced SQL processing
-    - sqlspec.core.parameters for optimized parameter handling
-    - sqlspec.core.cache for unified statement caching
-    - sqlspec.core.config for centralized configuration management
-
-    Compatibility:
-    - 100% backward compatibility with existing Oracle driver interface
-    - All existing sync Oracle tests pass without modification
-    - Complete StatementConfig API compatibility
-    - Preserved cursor management and exception handling patterns
+    """Synchronous Oracle Database driver.
+
+    Provides Oracle Database connectivity with parameter style conversion,
+    error handling, and transaction management.
     """
 
     __slots__ = ()
@@ -246,14 +222,14 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
-        # Enhanced configuration with global settings integration
+        # Configure with default settings
         if statement_config is None:
             cache_config = get_cache_config()
             enhanced_config = oracledb_statement_config.replace(
                 enable_caching=cache_config.compiled_cache_enabled,
-                enable_parsing=True,  # Default to enabled
-                enable_validation=True,  # Default to enabled
-                dialect="oracle",  # Use adapter-specific dialect
+                enable_parsing=True,
+                enable_validation=True,
+                dialect="oracle",
             )
             statement_config = enhanced_config
 
@@ -310,14 +286,14 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
 
-        # Enhanced parameter validation for executemany
+        # Parameter validation for executemany
         if not prepared_parameters:
             msg = "execute_many requires parameters"
             raise ValueError(msg)
 
         cursor.executemany(sql, prepared_parameters)
 
-        # Calculate affected rows based on parameter count for Oracle
+        # Calculate affected rows based on parameter count
         affected_rows = len(prepared_parameters) if prepared_parameters else 0
 
         return self.create_execution_result(cursor, rowcount_override=affected_rows, is_many_result=True)
@@ -330,7 +306,7 @@ class OracleSyncDriver(SyncDriverAdapterBase):
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
         cursor.execute(sql, prepared_parameters or {})
 
-        # Enhanced SELECT result processing for Oracle
+        # SELECT result processing for Oracle
         if statement.returns_rows():
             fetched_data = cursor.fetchall()
             column_names = [col[0] for col in cursor.description or []]
@@ -342,11 +318,11 @@ class OracleSyncDriver(SyncDriverAdapterBase):
                 cursor, selected_data=data, column_names=column_names, data_row_count=len(data), is_select_result=True
             )
 
-        # Enhanced non-SELECT result processing for Oracle
+        # Non-SELECT result processing
         affected_rows = cursor.rowcount if cursor.rowcount is not None else 0
         return self.create_execution_result(cursor, rowcount_override=affected_rows)
 
-    # Oracle transaction management with enhanced error handling
+    # Oracle transaction management
     def begin(self) -> None:
         """Begin a database transaction with enhanced error handling.
 
@@ -372,36 +348,10 @@ class OracleSyncDriver(SyncDriverAdapterBase):
 
 
 class OracleAsyncDriver(AsyncDriverAdapterBase):
-    """Enhanced Oracle Async driver with CORE_ROUND_3 architecture integration.
-
-    This async driver leverages the complete core module system for maximum Oracle performance:
-
-    Performance Improvements:
-    - 5-10x faster SQL compilation through single-pass processing
-    - 40-60% memory reduction through __slots__ optimization
-    - Enhanced caching for repeated statement execution
-    - Zero-copy parameter processing where possible
-    - Async-optimized resource management
-    - Optimized Oracle parameter style conversion (QMARK -> NAMED_COLON)
-
-    Oracle Features:
-    - Parameter style conversion (QMARK to NAMED_COLON/POSITIONAL_COLON)
-    - Oracle-specific type coercion and data handling
-    - Enhanced error categorization for Oracle database errors
-    - Transaction management with automatic commit/rollback
-    - Oracle-specific data handling and optimization
-
-    Core Integration Features:
-    - sqlspec.core.statement for enhanced SQL processing
-    - sqlspec.core.parameters for optimized parameter handling
-    - sqlspec.core.cache for unified statement caching
-    - sqlspec.core.config for centralized configuration management
-
-    Compatibility:
-    - 100% backward compatibility with existing Oracle driver interface
-    - All existing async Oracle tests pass without modification
-    - Complete StatementConfig API compatibility
-    - Preserved async cursor management and exception handling patterns
+    """Asynchronous Oracle Database driver.
+
+    Provides Oracle Database connectivity with parameter style conversion,
+    error handling, and transaction management for async operations.
     """
 
     __slots__ = ()
@@ -413,21 +363,21 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
-        # Enhanced configuration with global settings integration
+        # Configure with default settings
         if statement_config is None:
             cache_config = get_cache_config()
             enhanced_config = oracledb_statement_config.replace(
                 enable_caching=cache_config.compiled_cache_enabled,
-                enable_parsing=True,  # Default to enabled
-                enable_validation=True,  # Default to enabled
-                dialect="oracle",  # Use adapter-specific dialect
+                enable_parsing=True,
+                enable_validation=True,
+                dialect="oracle",
             )
             statement_config = enhanced_config
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: OracleAsyncConnection) -> OracleAsyncCursor:
-        """Create async context manager for Oracle cursor with enhanced resource management."""
+        """Create async context manager for Oracle cursor."""
         return OracleAsyncCursor(connection)
 
     def handle_database_exceptions(self) -> "AbstractAsyncContextManager[None]":
@@ -451,9 +401,8 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         return None
 
     async def _execute_script(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL script using enhanced statement splitting and parameter handling.
+        """Execute SQL script with statement splitting and parameter handling.
 
-        Uses core module optimization for statement parsing and parameter processing.
         Parameters are embedded as static values for script execution compatibility.
         """
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
@@ -471,33 +420,27 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
         )
 
     async def _execute_many(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute SQL with multiple parameter sets using optimized Oracle batch processing.
-
-        Leverages core parameter processing for enhanced Oracle type handling and parameter conversion.
-        """
+        """Execute SQL with multiple parameter sets using Oracle batch processing."""
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
 
-        # Enhanced parameter validation for executemany
+        # Parameter validation for executemany
         if not prepared_parameters:
             msg = "execute_many requires parameters"
             raise ValueError(msg)
 
         await cursor.executemany(sql, prepared_parameters)
 
-        # Calculate affected rows based on parameter count for Oracle
+        # Calculate affected rows based on parameter count
         affected_rows = len(prepared_parameters) if prepared_parameters else 0
 
         return self.create_execution_result(cursor, rowcount_override=affected_rows, is_many_result=True)
 
     async def _execute_statement(self, cursor: Any, statement: "SQL") -> "ExecutionResult":
-        """Execute single SQL statement with enhanced Oracle data handling and performance optimization.
-
-        Uses core processing for optimal parameter handling and Oracle result processing.
-        """
+        """Execute single SQL statement with Oracle data handling."""
         sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
         await cursor.execute(sql, prepared_parameters or {})
 
-        # Enhanced SELECT result processing for Oracle
+        # SELECT result processing for Oracle
         if statement.returns_rows():
             fetched_data = await cursor.fetchall()
             column_names = [col[0] for col in cursor.description or []]
@@ -509,20 +452,20 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
                 cursor, selected_data=data, column_names=column_names, data_row_count=len(data), is_select_result=True
             )
 
-        # Enhanced non-SELECT result processing for Oracle
+        # Non-SELECT result processing
         affected_rows = cursor.rowcount if cursor.rowcount is not None else 0
         return self.create_execution_result(cursor, rowcount_override=affected_rows)
 
-    # Oracle transaction management with enhanced async error handling
+    # Oracle transaction management
     async def begin(self) -> None:
-        """Begin a database transaction with enhanced async error handling.
+        """Begin a database transaction.
 
         Oracle handles transactions automatically, so this is a no-op.
         """
         # Oracle handles transactions implicitly
 
     async def rollback(self) -> None:
-        """Rollback the current transaction with enhanced async error handling."""
+        """Rollback the current transaction."""
         try:
             await self.connection.rollback()
         except oracledb.Error as e:
@@ -530,7 +473,7 @@ class OracleAsyncDriver(AsyncDriverAdapterBase):
             raise SQLSpecError(msg) from e
 
     async def commit(self) -> None:
-        """Commit the current transaction with enhanced async error handling."""
+        """Commit the current transaction."""
         try:
             await self.connection.commit()
         except oracledb.Error as e:

sqlspec/adapters/oracledb/migrations.py

@@ -0,0 +1,257 @@
+"""Oracle-specific migration implementations.
+
+This module provides Oracle Database-specific overrides for migration functionality
+to handle Oracle's unique SQL syntax requirements.
+"""
+
+import getpass
+from typing import TYPE_CHECKING, Any, Optional, cast
+
+from sqlspec._sql import sql
+from sqlspec.builder._ddl import CreateTable
+from sqlspec.migrations.base import BaseMigrationTracker
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
+
+__all__ = ("OracleAsyncMigrationTracker", "OracleSyncMigrationTracker")
+
+logger = get_logger("migrations.oracle")
+
+
+class OracleMigrationTrackerMixin:
+    """Mixin providing Oracle-specific migration table creation."""
+
+    __slots__ = ()
+
+    version_table: str
+
+    def _get_create_table_sql(self) -> CreateTable:
+        """Get Oracle-specific SQL builder for creating the tracking table.
+
+        Oracle doesn't support:
+        - CREATE TABLE IF NOT EXISTS (need try/catch logic)
+        - TEXT type (use VARCHAR2)
+        - DEFAULT before NOT NULL is required
+
+        Returns:
+            SQL builder object for Oracle table creation.
+        """
+        return (
+            sql.create_table(self.version_table)
+            .column("version_num", "VARCHAR2(32)", primary_key=True)
+            .column("description", "VARCHAR2(2000)")
+            .column("applied_at", "TIMESTAMP", default="CURRENT_TIMESTAMP")
+            .column("execution_time_ms", "INTEGER")
+            .column("checksum", "VARCHAR2(64)")
+            .column("applied_by", "VARCHAR2(255)")
+        )
+
+
+class OracleSyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTracker["SyncDriverAdapterBase"]):
+    """Oracle-specific sync migration tracker."""
+
+    __slots__ = ()
+
+    def ensure_tracking_table(self, driver: "SyncDriverAdapterBase") -> None:
+        """Create the migration tracking table if it doesn't exist.
+
+        Oracle doesn't support IF NOT EXISTS, so we check for table existence first.
+
+        Args:
+            driver: The database driver to use.
+        """
+
+        check_sql = (
+            sql.select(sql.count().as_("table_count"))
+            .from_("user_tables")
+            .where(sql.column("table_name") == self.version_table.upper())
+        )
+        result = driver.execute(check_sql)
+
+        if result.data[0]["TABLE_COUNT"] == 0:
+            driver.execute(self._get_create_table_sql())
+            self._safe_commit(driver)
+
+    def get_current_version(self, driver: "SyncDriverAdapterBase") -> "Optional[str]":
+        """Get the latest applied migration version.
+
+        Args:
+            driver: The database driver to use.
+
+        Returns:
+            The current migration version or None if no migrations applied.
+        """
+        result = driver.execute(self._get_current_version_sql())
+        return result.data[0]["VERSION_NUM"] if result.data else None
+
+    def get_applied_migrations(self, driver: "SyncDriverAdapterBase") -> "list[dict[str, Any]]":
+        """Get all applied migrations in order.
+
+        Args:
+            driver: The database driver to use.
+
+        Returns:
+            List of migration records as dictionaries.
+        """
+        result = driver.execute(self._get_applied_migrations_sql())
+        if not result.data:
+            return []
+
+        normalized_data = [{key.lower(): value for key, value in row.items()} for row in result.data]
+
+        return cast("list[dict[str, Any]]", normalized_data)
+
+    def record_migration(
+        self, driver: "SyncDriverAdapterBase", version: str, description: str, execution_time_ms: int, checksum: str
+    ) -> None:
+        """Record a successfully applied migration.
+
+        Args:
+            driver: The database driver to use.
+            version: Version number of the migration.
+            description: Description of the migration.
+            execution_time_ms: Execution time in milliseconds.
+            checksum: MD5 checksum of the migration content.
+        """
+
+        applied_by = getpass.getuser()
+
+        record_sql = self._get_record_migration_sql(version, description, execution_time_ms, checksum, applied_by)
+        driver.execute(record_sql)
+        self._safe_commit(driver)
+
+    def remove_migration(self, driver: "SyncDriverAdapterBase", version: str) -> None:
+        """Remove a migration record.
+
+        Args:
+            driver: The database driver to use.
+            version: Version number to remove.
+        """
+        remove_sql = self._get_remove_migration_sql(version)
+        driver.execute(remove_sql)
+        self._safe_commit(driver)
+
+    def _safe_commit(self, driver: "SyncDriverAdapterBase") -> None:
+        """Safely commit a transaction only if autocommit is disabled.
+
+        Args:
+            driver: The database driver to use.
+        """
+        try:
+            # Check driver features first (preferred approach)
+            if driver.driver_features.get("autocommit", False):
+                return
+
+            # Fallback to connection-level autocommit check
+            if driver.connection and driver.connection.autocommit:
+                return
+
+            driver.commit()
+        except Exception:
+            logger.debug("Failed to commit transaction, likely due to autocommit being enabled")
+
+
+class OracleAsyncMigrationTracker(OracleMigrationTrackerMixin, BaseMigrationTracker["AsyncDriverAdapterBase"]):
+    """Oracle-specific async migration tracker."""
+
+    __slots__ = ()
+
+    async def ensure_tracking_table(self, driver: "AsyncDriverAdapterBase") -> None:
+        """Create the migration tracking table if it doesn't exist.
+
+        Oracle doesn't support IF NOT EXISTS, so we check for table existence first.
+
+        Args:
+            driver: The database driver to use.
+        """
+
+        check_sql = (
+            sql.select(sql.count().as_("table_count"))
+            .from_("user_tables")
+            .where(sql.column("table_name") == self.version_table.upper())
+        )
+        result = await driver.execute(check_sql)
+
+        if result.data[0]["TABLE_COUNT"] == 0:
+            await driver.execute(self._get_create_table_sql())
+            await self._safe_commit_async(driver)
+
+    async def get_current_version(self, driver: "AsyncDriverAdapterBase") -> "Optional[str]":
+        """Get the latest applied migration version.
+
+        Args:
+            driver: The database driver to use.
+
+        Returns:
+            The current migration version or None if no migrations applied.
+        """
+        result = await driver.execute(self._get_current_version_sql())
+        return result.data[0]["VERSION_NUM"] if result.data else None
+
+    async def get_applied_migrations(self, driver: "AsyncDriverAdapterBase") -> "list[dict[str, Any]]":
+        """Get all applied migrations in order.
+
+        Args:
+            driver: The database driver to use.
+
+        Returns:
+            List of migration records as dictionaries.
+        """
+        result = await driver.execute(self._get_applied_migrations_sql())
+        if not result.data:
+            return []
+
+        normalized_data = [{key.lower(): value for key, value in row.items()} for row in result.data]
+
+        return cast("list[dict[str, Any]]", normalized_data)
+
+    async def record_migration(
+        self, driver: "AsyncDriverAdapterBase", version: str, description: str, execution_time_ms: int, checksum: str
+    ) -> None:
+        """Record a successfully applied migration.
+
+        Args:
+            driver: The database driver to use.
+            version: Version number of the migration.
+            description: Description of the migration.
+            execution_time_ms: Execution time in milliseconds.
+            checksum: MD5 checksum of the migration content.
+        """
+
+        applied_by = getpass.getuser()
+
+        record_sql = self._get_record_migration_sql(version, description, execution_time_ms, checksum, applied_by)
+        await driver.execute(record_sql)
+        await self._safe_commit_async(driver)
+
+    async def remove_migration(self, driver: "AsyncDriverAdapterBase", version: str) -> None:
+        """Remove a migration record.
+
+        Args:
+            driver: The database driver to use.
+            version: Version number to remove.
+        """
+        remove_sql = self._get_remove_migration_sql(version)
+        await driver.execute(remove_sql)
+        await self._safe_commit_async(driver)
+
+    async def _safe_commit_async(self, driver: "AsyncDriverAdapterBase") -> None:
+        """Safely commit a transaction only if autocommit is disabled.
+
+        Args:
+            driver: The database driver to use.
+        """
+        try:
+            # Check driver features first (preferred approach)
+            if driver.driver_features.get("autocommit", False):
+                return
+
+            # Fallback to connection-level autocommit check
+            if driver.connection and driver.connection.autocommit:
+                return
+
+            await driver.commit()
+        except Exception:
+            logger.debug("Failed to commit transaction, likely due to autocommit being enabled")

sqlspec/adapters/psqlpy/config.py

@@ -1,4 +1,4 @@
-"""Psqlpy database configuration with direct field-based configuration."""
+"""Psqlpy database configuration."""
 
 import logging
 from collections.abc import AsyncGenerator
@@ -77,7 +77,7 @@ __all__ = ("PsqlpyConfig", "PsqlpyConnectionParams", "PsqlpyCursor", "PsqlpyPool
 
 
 class PsqlpyConfig(AsyncDatabaseConfig[PsqlpyConnection, ConnectionPool, PsqlpyDriver]):
-    """Configuration for Psqlpy asynchronous database connections with direct field-based configuration."""
+    """Configuration for Psqlpy asynchronous database connections."""
 
     driver_type: ClassVar[type[PsqlpyDriver]] = PsqlpyDriver
     connection_type: "ClassVar[type[PsqlpyConnection]]" = PsqlpyConnection
@@ -86,17 +86,19 @@ class PsqlpyConfig(AsyncDatabaseConfig[PsqlpyConnection, ConnectionPool, PsqlpyD
         self,
         *,
         pool_config: Optional[Union[PsqlpyPoolParams, dict[str, Any]]] = None,
-        statement_config: Optional[StatementConfig] = None,
         pool_instance: Optional[ConnectionPool] = None,
         migration_config: Optional[dict[str, Any]] = None,
+        statement_config: Optional[StatementConfig] = None,
+        driver_features: Optional[dict[str, Any]] = None,
     ) -> None:
-        """Initialize Psqlpy asynchronous configuration.
+        """Initialize Psqlpy configuration.
 
         Args:
-            pool_config: Pool configuration parameters (TypedDict or dict)
+            pool_config: Pool configuration parameters
             pool_instance: Existing connection pool instance to use
-            statement_config: Default SQL statement configuration
             migration_config: Migration configuration
+            statement_config: SQL statement configuration
+            driver_features: Driver feature configuration
         """
         processed_pool_config: dict[str, Any] = dict(pool_config) if pool_config else {}
         if "extra" in processed_pool_config:
@@ -107,6 +109,7 @@ class PsqlpyConfig(AsyncDatabaseConfig[PsqlpyConnection, ConnectionPool, PsqlpyD
             pool_instance=pool_instance,
             migration_config=migration_config,
             statement_config=statement_config or psqlpy_statement_config,
+            driver_features=driver_features or {},
         )
 
     def _get_pool_config_dict(self) -> dict[str, Any]:
@@ -145,6 +148,10 @@ class PsqlpyConfig(AsyncDatabaseConfig[PsqlpyConnection, ConnectionPool, PsqlpyD
             logger.exception("Failed to close psqlpy connection pool", extra={"adapter": "psqlpy", "error": str(e)})
             raise
 
+    async def close_pool(self) -> None:
+        """Close the connection pool."""
+        await self._close_pool()
+
     async def create_connection(self) -> "PsqlpyConnection":
         """Create a single async connection (not from pool).
 
@@ -203,9 +210,6 @@ class PsqlpyConfig(AsyncDatabaseConfig[PsqlpyConnection, ConnectionPool, PsqlpyD
     def get_signature_namespace(self) -> "dict[str, type[Any]]":
         """Get the signature namespace for Psqlpy types.
 
-        This provides all Psqlpy-specific types that Litestar needs to recognize
-        to avoid serialization attempts.
-
         Returns:
             Dictionary mapping type names to types.
         """