sqlspec 0.18.0__py3-none-any.whl → 0.20.0__py3-none-any.whl

sqlspec/config.py

@@ -11,8 +11,11 @@ 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__ = (
@@ -45,7 +48,7 @@ logger = get_logger("config")
 
 
 class LifecycleConfig(TypedDict, total=False):
-    """Lifecycle hooks for all adapters.
+    """Lifecycle hooks for database adapters.
 
     Each hook accepts a list of callables to support multiple handlers.
     """
@@ -64,7 +67,7 @@ class LifecycleConfig(TypedDict, total=False):
 class MigrationConfig(TypedDict, total=False):
     """Configuration options for database migrations.
 
-    All fields are optional with sensible defaults.
+    All fields are optional with default values.
     """
 
     script_location: NotRequired[str]
@@ -76,11 +79,24 @@ class MigrationConfig(TypedDict, total=False):
     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
@@ -144,18 +160,148 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     def get_signature_namespace(self) -> "dict[str, type[Any]]":
         """Get the signature namespace for this database configuration.
 
-        This method returns a dictionary of type names to types that should be
-        registered with Litestar's signature namespace to prevent serialization
-        attempts on database-specific types.
+        Returns a dictionary of type names to types that should be registered
+        with Litestar's signature namespace to prevent serialization attempts
+        on database-specific types.
 
         Returns:
             Dictionary mapping type names to types.
         """
         return {}
 
+    def _initialize_migration_components(self) -> None:
+        """Initialize migration loader and commands with necessary imports.
+
+        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:
+            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:
+            MigrationCommands instance for this config.
+        """
+        return self._migration_commands
+
+    def get_migration_loader(self) -> "SQLFileLoader":
+        """Get the SQL loader for migration files.
+
+        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:
+            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."""
+    """Base class for sync database configurations that do not implement a pool."""
 
     __slots__ = ("connection_config",)
     is_async: "ClassVar[bool]" = False
@@ -173,6 +319,7 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
         self.pool_instance = None
         self.connection_config = connection_config or {}
         self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self._initialize_migration_components()
 
         if statement_config is None:
             default_parameter_config = ParameterStyleConfig(
@@ -208,7 +355,7 @@ class NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 
 
 class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
-    """Base class for an async database configurations that do not implement a pool."""
+    """Base class for async database configurations that do not implement a pool."""
 
     __slots__ = ("connection_config",)
     is_async: "ClassVar[bool]" = True
@@ -226,6 +373,7 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
         self.pool_instance = None
         self.connection_config = connection_config or {}
         self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self._initialize_migration_components()
 
         if statement_config is None:
             default_parameter_config = ParameterStyleConfig(
@@ -261,7 +409,7 @@ class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
 
 
 class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
-    """Generic Sync Database Configuration."""
+    """Base class for sync database configurations with connection pooling."""
 
     __slots__ = ("pool_config",)
     is_async: "ClassVar[bool]" = False
@@ -280,6 +428,7 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
         self.pool_instance = pool_instance
         self.pool_config = pool_config or {}
         self.migration_config: Union[dict[str, Any], MigrationConfig] = migration_config or {}
+        self._initialize_migration_components()
 
         if statement_config is None:
             default_parameter_config = ParameterStyleConfig(
@@ -337,7 +486,7 @@ class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
 
 
 class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
-    """Generic Async Database Configuration."""
+    """Base class for async database configurations with connection pooling."""
 
     __slots__ = ("pool_config",)
     is_async: "ClassVar[bool]" = True
@@ -356,6 +505,7 @@ class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
         self.pool_instance = pool_instance
         self.pool_config = pool_config or {}
         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/compiler.py

@@ -17,6 +17,7 @@ from sqlglot.errors import ParseError
 from typing_extensions import Literal
 
 from sqlspec.core.parameters import ParameterProcessor
+from sqlspec.exceptions import SQLSpecError
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
@@ -61,6 +62,8 @@ class CompiledSQL:
     """Compiled SQL result.
 
     Contains the result of SQL compilation with information needed for execution.
+    Immutable container holding compiled SQL text, processed parameters, operation
+    type, and execution metadata.
     """
 
     __slots__ = (
@@ -133,7 +136,9 @@ class CompiledSQL:
 class SQLProcessor:
     """SQL processor with compilation and caching.
 
-    Processes SQL statements with parameter processing and caching.
+    Processes SQL statements by compiling them into executable format with
+    parameter substitution. Includes LRU-style caching for compilation results
+    to avoid re-processing identical statements.
     """
 
     __slots__ = ("_cache", "_cache_hits", "_cache_misses", "_config", "_max_cache_size", "_parameter_processor")
@@ -157,7 +162,7 @@ class SQLProcessor:
 
         Args:
             sql: SQL string for compilation
-            parameters: Parameter values
+            parameters: Parameter values for substitution
             is_many: Whether this is for execute_many operation
 
         Returns:
@@ -261,6 +266,9 @@ class SQLProcessor:
                 supports_many=isinstance(final_params, list) and len(final_params) > 0,
             )
 
+        except SQLSpecError:
+            # Re-raise SQLSpecError (validation errors, parameter mismatches) - these should fail hard
+            raise
         except Exception as e:
             logger.warning("Compilation failed, using fallback: %s", e)
             return CompiledSQL(compiled_sql=sql, execution_parameters=parameters, operation_type="UNKNOWN")
@@ -340,7 +348,7 @@ class SQLProcessor:
         return sql, parameters
 
     def clear_cache(self) -> None:
-        """Clear cache."""
+        """Clear compilation cache and reset statistics."""
         self._cache.clear()
         self._cache_hits = 0
         self._cache_misses = 0

sqlspec/core/filters.py

@@ -196,7 +196,10 @@ class BeforeAfterFilter(StatementFilter):
 
 
 class OnBeforeAfterFilter(StatementFilter):
-    """Data required to filter a query on a ``datetime`` column."""
+    """Filter for inclusive datetime range queries.
+
+    Applies WHERE clauses for on-or-before/on-or-after datetime filtering.
+    """
 
     __slots__ = ("_param_name_on_or_after", "_param_name_on_or_before", "field_name", "on_or_after", "on_or_before")
 
@@ -277,7 +280,7 @@ class OnBeforeAfterFilter(StatementFilter):
 
 
 class InAnyFilter(StatementFilter, ABC, Generic[T]):
-    """Subclass for methods that have a `prefer_any` attribute."""
+    """Base class for collection-based filters that support ANY operations."""
 
     __slots__ = ()
 
@@ -346,7 +349,10 @@ class InCollectionFilter(InAnyFilter[T]):
 
 
 class NotInCollectionFilter(InAnyFilter[T]):
-    """Data required to construct a ``WHERE ... NOT IN (...)`` clause."""
+    """Filter for NOT IN clause queries.
+
+    Constructs WHERE ... NOT IN (...) clauses.
+    """
 
     __slots__ = ("_param_names", "field_name", "values")
 
@@ -401,7 +407,10 @@ class NotInCollectionFilter(InAnyFilter[T]):
 
 
 class AnyCollectionFilter(InAnyFilter[T]):
-    """Data required to construct a ``WHERE column_name = ANY (array_expression)`` clause."""
+    """Filter for PostgreSQL-style ANY clause queries.
+
+    Constructs WHERE column_name = ANY (array_expression) clauses.
+    """
 
     __slots__ = ("_param_names", "field_name", "values")
 
@@ -460,7 +469,10 @@ class AnyCollectionFilter(InAnyFilter[T]):
 
 
 class NotAnyCollectionFilter(InAnyFilter[T]):
-    """Data required to construct a ``WHERE NOT (column_name = ANY (array_expression))`` clause."""
+    """Filter for PostgreSQL-style NOT ANY clause queries.
+
+    Constructs WHERE NOT (column_name = ANY (array_expression)) clauses.
+    """
 
     __slots__ = ("_param_names", "field_name", "values")
 
@@ -514,7 +526,7 @@ class NotAnyCollectionFilter(InAnyFilter[T]):
 
 
 class PaginationFilter(StatementFilter, ABC):
-    """Subclass for methods that function as a pagination type."""
+    """Base class for pagination-related filters."""
 
     __slots__ = ()
 
@@ -524,7 +536,10 @@ class PaginationFilter(StatementFilter, ABC):
 
 
 class LimitOffsetFilter(PaginationFilter):
-    """Data required to add limit/offset filtering to a query."""
+    """Filter for LIMIT and OFFSET clauses.
+
+    Adds pagination support through LIMIT/OFFSET SQL clauses.
+    """
 
     __slots__ = ("_limit_param_name", "_offset_param_name", "limit", "offset")
 
@@ -576,7 +591,10 @@ class LimitOffsetFilter(PaginationFilter):
 
 
 class OrderByFilter(StatementFilter):
-    """Data required to construct a ``ORDER BY ...`` clause."""
+    """Filter for ORDER BY clauses.
+
+    Adds sorting capability to SQL queries.
+    """
 
     __slots__ = ("field_name", "sort_order")
 
@@ -694,7 +712,10 @@ class SearchFilter(StatementFilter):
 
 
 class NotInSearchFilter(SearchFilter):
-    """Data required to construct a ``WHERE field_name NOT LIKE '%' || :value || '%'`` clause."""
+    """Filter for negated text search queries.
+
+    Constructs WHERE field_name NOT LIKE '%value%' clauses.
+    """
 
     __slots__ = ()