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

sqlspec/config.py

@@ -5,13 +5,17 @@ from typing_extensions import NotRequired, TypedDict
 
 from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
 from sqlspec.core.statement import StatementConfig
+from sqlspec.migrations.tracker import AsyncMigrationTracker, SyncMigrationTracker
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable
     from contextlib import AbstractAsyncContextManager, AbstractContextManager
+    from pathlib import Path
 
     from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
+    from sqlspec.loader import SQLFileLoader
+    from sqlspec.migrations.commands import MigrationCommands
 
 
 __all__ = (
@@ -21,6 +25,7 @@ __all__ = (
     "DatabaseConfigProtocol",
     "DriverT",
     "LifecycleConfig",
+    "MigrationConfig",
     "NoPoolAsyncConfig",
     "NoPoolSyncConfig",
     "SyncConfigT",
@@ -43,7 +48,7 @@ logger = get_logger("config")
 
 
 class LifecycleConfig(TypedDict, total=False):
-    """Universal lifecycle hooks for all adapters.
+    """Lifecycle hooks for all adapters.
 
     Each hook accepts a list of callables to support multiple handlers.
     """
@@ -59,10 +64,39 @@ class LifecycleConfig(TypedDict, total=False):
     on_error: NotRequired[list[Callable[[Exception, str, dict], None]]]
 
 
+class MigrationConfig(TypedDict, total=False):
+    """Configuration options for database migrations.
+
+    All fields are optional with sensible defaults.
+    """
+
+    script_location: NotRequired[str]
+    """Path to the migrations directory. Defaults to 'migrations'."""
+
+    version_table_name: NotRequired[str]
+    """Name of the table used to track applied migrations. Defaults to 'sqlspec_migrations'."""
+
+    project_root: NotRequired[str]
+    """Path to the project root directory. Used for relative path resolution."""
+
+    enabled: NotRequired[bool]
+    """Whether this configuration should be included in CLI operations. Defaults to True."""
+
+
 class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     """Protocol defining the interface for database configurations."""
 
-    __slots__ = ("driver_features", "migration_config", "pool_instance", "statement_config")
+    __slots__ = (
+        "_migration_commands",
+        "_migration_loader",
+        "driver_features",
+        "migration_config",
+        "pool_instance",
+        "statement_config",
+    )
+
+    _migration_loader: "SQLFileLoader"
+    _migration_commands: "MigrationCommands"
     driver_type: "ClassVar[type[Any]]"
     connection_type: "ClassVar[type[Any]]"
     is_async: "ClassVar[bool]" = False
@@ -73,7 +107,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     supports_native_parquet_export: "ClassVar[bool]" = False
     statement_config: "StatementConfig"
     pool_instance: "Optional[PoolT]"
-    migration_config: "dict[str, Any]"
+    migration_config: "Union[dict[str, Any], MigrationConfig]"
 
     def __hash__(self) -> int:
         return id(self)
@@ -135,6 +169,136 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         """
         return {}
 
+    def _initialize_migration_components(self) -> None:
+        """Initialize migration loader and commands with necessary imports.
+
+        This method handles the circular import between config and commands
+        by importing at runtime when needed.
+        """
+        from sqlspec.loader import SQLFileLoader
+        from sqlspec.migrations.commands import MigrationCommands
+
+        self._migration_loader = SQLFileLoader()
+        self._migration_commands = MigrationCommands(self)  # type: ignore[arg-type]
+
+    def _ensure_migration_loader(self) -> "SQLFileLoader":
+        """Get the migration SQL loader and auto-load files if needed.
+
+        Returns:
+            The SQLFileLoader instance for migration files.
+        """
+        # Auto-load migration files from configured migration path if it exists
+        migration_config = self.migration_config or {}
+        script_location = migration_config.get("script_location", "migrations")
+
+        from pathlib import Path
+
+        migration_path = Path(script_location)
+        if migration_path.exists() and not self._migration_loader.list_files():
+            self._migration_loader.load_sql(migration_path)
+            logger.debug("Auto-loaded migration SQL files from %s", migration_path)
+
+        return self._migration_loader
+
+    def _ensure_migration_commands(self) -> "MigrationCommands":
+        """Get the migration commands instance.
+
+        Returns:
+            The MigrationCommands instance for this config.
+        """
+        return self._migration_commands
+
+    def get_migration_loader(self) -> "SQLFileLoader":
+        """Get the SQL loader for migration files.
+
+        This provides access to migration SQL files loaded from the configured
+        script_location directory. Files are loaded lazily on first access.
+
+        Returns:
+            SQLFileLoader instance with migration files loaded.
+        """
+        return self._ensure_migration_loader()
+
+    def load_migration_sql_files(self, *paths: "Union[str, Path]") -> None:
+        """Load additional migration SQL files from specified paths.
+
+        Args:
+            *paths: One or more file paths or directory paths to load migration SQL files from.
+        """
+        from pathlib import Path
+
+        loader = self._ensure_migration_loader()
+        for path in paths:
+            path_obj = Path(path)
+            if path_obj.exists():
+                loader.load_sql(path_obj)
+                logger.debug("Loaded migration SQL files from %s", path_obj)
+            else:
+                logger.warning("Migration path does not exist: %s", path_obj)
+
+    def get_migration_commands(self) -> "MigrationCommands":
+        """Get migration commands for this configuration.
+
+        Returns:
+            MigrationCommands instance configured for this database.
+        """
+        return self._ensure_migration_commands()
+
+    def migrate_up(self, revision: str = "head") -> None:
+        """Apply migrations up to the specified revision.
+
+        Args:
+            revision: Target revision or "head" for latest. Defaults to "head".
+        """
+        commands = self._ensure_migration_commands()
+        commands.upgrade(revision)
+
+    def migrate_down(self, revision: str = "-1") -> None:
+        """Apply migrations down to the specified revision.
+
+        Args:
+            revision: Target revision, "-1" for one step back, or "base" for all migrations. Defaults to "-1".
+        """
+        commands = self._ensure_migration_commands()
+        commands.downgrade(revision)
+
+    def get_current_migration(self, verbose: bool = False) -> "Optional[str]":
+        """Get the current migration version.
+
+        Args:
+            verbose: Whether to show detailed migration history.
+
+        Returns:
+            The current migration version or None if no migrations applied.
+        """
+        commands = self._ensure_migration_commands()
+        return commands.current(verbose=verbose)
+
+    def create_migration(self, message: str, file_type: str = "sql") -> None:
+        """Create a new migration file.
+
+        Args:
+            message: Description for the migration.
+            file_type: Type of migration file to create ('sql' or 'py'). Defaults to 'sql'.
+        """
+        commands = self._ensure_migration_commands()
+        commands.revision(message, file_type)
+
+    def init_migrations(self, directory: "Optional[str]" = None, package: bool = True) -> None:
+        """Initialize migration directory structure.
+
+        Args:
+            directory: Directory to initialize migrations in. Uses script_location from migration_config if not provided.
+            package: Whether to create __init__.py file. Defaults to True.
+        """
+        if directory is None:
+            migration_config = self.migration_config or {}
+            directory = migration_config.get("script_location") or "migrations"
+
+        commands = self._ensure_migration_commands()
+        assert directory is not None
+        commands.init(directory, package)
+
 
 class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     """Base class for a sync database configurations that do not implement a pool."""
@@ -142,18 +306,20 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     __slots__ = ("connection_config",)
     is_async: "ClassVar[bool]" = False
     supports_connection_pooling: "ClassVar[bool]" = False
+    migration_tracker_type: "ClassVar[type[Any]]" = SyncMigrationTracker
 
     def __init__(
         self,
         *,
         connection_config: Optional[dict[str, Any]] = None,
-        migration_config: "Optional[dict[str, Any]]" = None,
+        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
         self.pool_instance = None
         self.connection_config = connection_config or {}
-        self.migration_config: dict[str, Any] = migration_config if migration_config is not None else {}
+        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self._initialize_migration_components()
 
         if statement_config is None:
             default_parameter_config = ParameterStyleConfig(
@@ -192,21 +358,22 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
     """Base class for an async database configurations that do not implement a pool."""
 
     __slots__ = ("connection_config",)
-
     is_async: "ClassVar[bool]" = True
     supports_connection_pooling: "ClassVar[bool]" = False
+    migration_tracker_type: "ClassVar[type[Any]]" = AsyncMigrationTracker
 
     def __init__(
         self,
         *,
         connection_config: "Optional[dict[str, Any]]" = None,
-        migration_config: "Optional[dict[str, Any]]" = None,
+        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
         self.pool_instance = None
         self.connection_config = connection_config or {}
-        self.migration_config: dict[str, Any] = migration_config if migration_config is not None else {}
+        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self._initialize_migration_components()
 
         if statement_config is None:
             default_parameter_config = ParameterStyleConfig(
@@ -245,22 +412,23 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     """Generic Sync Database Configuration."""
 
     __slots__ = ("pool_config",)
-
     is_async: "ClassVar[bool]" = False
     supports_connection_pooling: "ClassVar[bool]" = True
+    migration_tracker_type: "ClassVar[type[Any]]" = SyncMigrationTracker
 
     def __init__(
         self,
         *,
         pool_config: "Optional[dict[str, Any]]" = None,
         pool_instance: "Optional[PoolT]" = None,
-        migration_config: "Optional[dict[str, Any]]" = None,
+        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
         self.pool_instance = pool_instance
         self.pool_config = pool_config or {}
-        self.migration_config: dict[str, Any] = migration_config if migration_config is not None else {}
+        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self._initialize_migration_components()
 
         if statement_config is None:
             default_parameter_config = ParameterStyleConfig(
@@ -321,22 +489,23 @@ class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
     """Generic Async Database Configuration."""
 
     __slots__ = ("pool_config",)
-
     is_async: "ClassVar[bool]" = True
     supports_connection_pooling: "ClassVar[bool]" = True
+    migration_tracker_type: "ClassVar[type[Any]]" = AsyncMigrationTracker
 
     def __init__(
         self,
         *,
         pool_config: "Optional[dict[str, Any]]" = None,
         pool_instance: "Optional[PoolT]" = None,
-        migration_config: "Optional[dict[str, Any]]" = None,
+        migration_config: "Optional[Union[dict[str, Any], MigrationConfig]]" = None,
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
         self.pool_instance = pool_instance
         self.pool_config = pool_config or {}
-        self.migration_config: dict[str, Any] = migration_config if migration_config is not None else {}
+        self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self._initialize_migration_components()
 
         if statement_config is None:
             self.statement_config = StatementConfig(

sqlspec/core/__init__.py

@@ -1,17 +1,92 @@
-"""SQLSpec Core Module - SQL Processing System.
-
-This module provides the core SQL processing components including statement handling,
-parameter processing, compilation, and result management.
-
-Components:
-- statement.py: SQL class with StatementConfig
-- parameters.py: Parameter processing pipeline
-- compiler.py: SQL compilation with caching
-- result.py: Result classes for query execution
-- filters.py: Statement filter system
-- cache.py: Unified caching system
-- splitter.py: SQL statement splitter
-- hashing.py: Cache key generation
+"""SQLSpec Core Module - High-Performance SQL Processing System.
+
+This module provides the core SQL processing infrastructure for SQLSpec, implementing
+a complete pipeline for SQL statement compilation, parameter processing, caching,
+and result management. All components are optimized for MyPyC compilation and
+designed for maximum performance with minimal overhead.
+
+Architecture Overview:
+    The core module implements a single-pass processing pipeline where SQL statements
+    are parsed once, transformed once, and validated once. The SQL object serves as
+    the single source of truth throughout the system.
+
+Key Components:
+    statement.py: SQL statement representation and configuration management
+        - SQL class for statement encapsulation with lazy compilation
+        - StatementConfig for processing pipeline configuration
+        - ProcessedState for cached compilation results
+        - Support for execute_many and script execution modes
+
+    parameters.py: Type-safe parameter processing and style conversion
+        - Automatic parameter style detection and conversion
+        - Support for QMARK (?), NAMED (:name), NUMERIC ($1), FORMAT (%s) styles
+        - Parameter validation and type coercion
+        - Batch parameter handling for execute_many operations
+
+    compiler.py: SQL compilation with validation and optimization
+        - SQLProcessor for statement compilation and validation
+        - Operation type detection (SELECT, INSERT, UPDATE, DELETE, etc.)
+        - AST-based SQL analysis using SQLGlot
+        - Support for multiple SQL dialects
+        - Compiled result caching for performance
+
+    result.py: Comprehensive result handling for all SQL operations
+        - SQLResult for standard query results with metadata
+        - ArrowResult for Apache Arrow format integration
+        - Support for DML operations with RETURNING clauses
+        - Script execution result aggregation
+        - Iterator protocol support for result rows
+
+    filters.py: Composable SQL statement filters
+        - BeforeAfterFilter for date range filtering
+        - InCollectionFilter for IN clause generation
+        - LimitOffsetFilter for pagination
+        - OrderByFilter for dynamic sorting
+        - SearchFilter for text search operations
+        - Parameter conflict resolution
+
+    cache.py: Unified caching system with LRU eviction
+        - UnifiedCache with configurable TTL and size limits
+        - StatementCache for compiled SQL statements
+        - ExpressionCache for parsed SQLGlot expressions
+        - ParameterCache for processed parameters
+        - Thread-safe operations with fine-grained locking
+        - Cache statistics and monitoring
+
+    splitter.py: Dialect-aware SQL script splitting
+        - Support for Oracle PL/SQL, T-SQL, PostgreSQL, MySQL
+        - Proper handling of block structures (BEGIN/END)
+        - Dollar-quoted string support for PostgreSQL
+        - Batch separator recognition (GO for T-SQL)
+        - Comment and string literal preservation
+
+    hashing.py: Efficient cache key generation
+        - SQL statement hashing with parameter consideration
+        - Expression tree hashing for AST caching
+        - Parameter set hashing for batch operations
+        - Optimized hash computation with caching
+
+Performance Optimizations:
+    - MyPyC compilation support with proper annotations
+    - __slots__ usage for memory efficiency
+    - Final annotations for constant folding
+    - Lazy evaluation and compilation
+    - Comprehensive result caching
+    - Minimal object allocation in hot paths
+
+Thread Safety:
+    All caching components are thread-safe with RLock protection.
+    The processing pipeline is stateless and safe for concurrent use.
+
+Example Usage:
+    >>> from sqlspec.core import SQL, StatementConfig
+    >>> config = StatementConfig(dialect="postgresql")
+    >>> stmt = SQL(
+    ...     "SELECT * FROM users WHERE id = ?",
+    ...     1,
+    ...     statement_config=config,
+    ... )
+    >>> compiled_sql, params = stmt.compile()
 """
 
 from sqlspec.core import filters