sqlspec 0.13.1__py3-none-any.whl → 0.14.1__py3-none-any.whl

sqlspec/driver/mixins/_result_utils.py

@@ -52,8 +52,6 @@ def _default_msgspec_deserializer(
 
 
 class ToSchemaMixin:
-    __slots__ = ()
-
     @staticmethod
     def _determine_operation_type(statement: "Any") -> OperationType:
         """Determine operation type from SQL statement expression.

sqlspec/driver/mixins/_sql_translator.py

@@ -10,8 +10,6 @@ __all__ = ("SQLTranslatorMixin",)
 class SQLTranslatorMixin:
     """Mixin for drivers supporting SQL translation."""
 
-    __slots__ = ()
-
     def convert_to_dialect(self, statement: "Statement", to_dialect: DialectType = None, pretty: bool = True) -> str:
         parsed_expression: exp.Expression
         if statement is not None and isinstance(statement, SQL):

sqlspec/driver/mixins/_storage.py

@@ -44,8 +44,6 @@ WINDOWS_PATH_MIN_LENGTH = 3
 class StorageMixinBase(ABC):
     """Base class with common storage functionality."""
 
-    __slots__ = ()
-
     config: Any
     _connection: Any
     dialect: "DialectType"
@@ -144,8 +142,6 @@ class StorageMixinBase(ABC):
 class SyncStorageMixin(StorageMixinBase):
     """Unified storage operations for synchronous drivers."""
 
-    __slots__ = ()
-
     def ingest_arrow_table(self, table: "ArrowTable", table_name: str, mode: str = "create", **options: Any) -> int:
         """Ingest an Arrow table into the database.
 
@@ -211,7 +207,7 @@ class SyncStorageMixin(StorageMixinBase):
         # disable parameter validation entirely to allow transformer-added parameters
         if params is None and _config and _config.enable_transformations:
             # Disable validation entirely for transformer-generated parameters
-            _config = replace(_config, strict_mode=False, enable_validation=False)
+            _config = replace(_config, enable_validation=False)
 
         # Only pass params if it's not None to avoid adding None as a parameter
         if params is not None:
@@ -294,12 +290,8 @@ class SyncStorageMixin(StorageMixinBase):
             _config = self.config
             if _config and not _config.dialect:
                 _config = replace(_config, dialect=self.dialect)
-        if _config and _config.enable_transformations:
-            _config = replace(_config, enable_transformations=False)
 
-        sql = (
-            SQL(statement, parameters=params, config=_config) if params is not None else SQL(statement, config=_config)
-        )
+        sql = SQL(statement, *params, config=_config) if params else SQL(statement, config=_config)
         for filter_ in filters:
             sql = sql.filter(filter_)
 
@@ -576,8 +568,6 @@ class SyncStorageMixin(StorageMixinBase):
 class AsyncStorageMixin(StorageMixinBase):
     """Unified storage operations for asynchronous drivers."""
 
-    __slots__ = ()
-
     async def ingest_arrow_table(
         self, table: "ArrowTable", table_name: str, mode: str = "create", **options: Any
     ) -> int:
@@ -650,7 +640,7 @@ class AsyncStorageMixin(StorageMixinBase):
         # disable parameter validation entirely to allow transformer-added parameters
         if params is None and _config and _config.enable_transformations:
             # Disable validation entirely for transformer-generated parameters
-            _config = replace(_config, strict_mode=False, enable_validation=False)
+            _config = replace(_config, enable_validation=False)
 
         # Only pass params if it's not None to avoid adding None as a parameter
         if params is not None:
@@ -703,12 +693,8 @@ class AsyncStorageMixin(StorageMixinBase):
             _config = self.config
             if _config and not _config.dialect:
                 _config = replace(_config, dialect=self.dialect)
-        if _config and _config.enable_transformations:
-            _config = replace(_config, enable_transformations=False)
 
-        sql = (
-            SQL(statement, parameters=params, config=_config) if params is not None else SQL(statement, config=_config)
-        )
+        sql = SQL(statement, *params, config=_config) if params else SQL(statement, config=_config)
         for filter_ in filters:
             sql = sql.filter(filter_)
 

sqlspec/driver/mixins/_type_coercion.py

@@ -22,8 +22,6 @@ class TypeCoercionMixin:
     and convert values to database-specific types.
     """
 
-    __slots__ = ()
-
     def _process_parameters(self, parameters: "SQLParameterType") -> "SQLParameterType":
         """Process parameters, extracting values from TypedParameter objects.
 

sqlspec/driver/parameters.py

@@ -13,8 +13,8 @@ if TYPE_CHECKING:
     from sqlspec.typing import StatementParameters
 
 __all__ = (
+    "convert_parameter_sequence",
     "convert_parameters_to_positional",
-    "normalize_parameter_sequence",
     "process_execute_many_parameters",
     "separate_filters_and_parameters",
     "should_use_transaction",
@@ -62,19 +62,19 @@ def process_execute_many_parameters(
     param_sequence = param_values[0] if param_values else None
 
     # Normalize the parameter sequence
-    param_sequence = normalize_parameter_sequence(param_sequence)
+    param_sequence = convert_parameter_sequence(param_sequence)
 
     return filters, param_sequence
 
 
-def normalize_parameter_sequence(params: Any) -> Optional[list[Any]]:
+def convert_parameter_sequence(params: Any) -> Optional[list[Any]]:
     """Normalize a parameter sequence to a list format.
 
     Args:
         params: Parameter sequence in various formats
 
     Returns:
-        Normalized list of parameters or None
+        converted list of parameters or None
     """
     if params is None:
         return None

sqlspec/extensions/aiosql/adapter.py

@@ -38,7 +38,7 @@ def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
         dialect: Original dialect name (can be str, Dialect, type[Dialect], or None)
 
     Returns:
-        Normalized dialect name
+        converted dialect name
     """
     if dialect is None:
         return "sql"
@@ -84,9 +84,9 @@ class _AiosqlAdapterBase:
 
     def _create_sql_object(self, sql: str, parameters: "Any" = None) -> SQL:
         """Create SQL object with proper configuration."""
-        config = SQLConfig(strict_mode=False, enable_validation=False)
-        normalized_dialect = _normalize_dialect(self.driver.dialect)
-        return SQL(sql, parameters, config=config, dialect=normalized_dialect)
+        config = SQLConfig(enable_validation=False)
+        converted_dialect = _normalize_dialect(self.driver.dialect)
+        return SQL(sql, parameters, config=config, dialect=converted_dialect)
 
 
 class AiosqlSyncAdapter(_AiosqlAdapterBase):

sqlspec/extensions/litestar/__init__.py

@@ -1,5 +1,6 @@
 from sqlspec.extensions.litestar import handlers, providers
+from sqlspec.extensions.litestar.cli import database_group
 from sqlspec.extensions.litestar.config import DatabaseConfig
 from sqlspec.extensions.litestar.plugin import SQLSpec
 
-__all__ = ("DatabaseConfig", "SQLSpec", "handlers", "providers")
+__all__ = ("DatabaseConfig", "SQLSpec", "database_group", "handlers", "providers")

sqlspec/extensions/litestar/cli.py

@@ -0,0 +1,48 @@
+"""Litestar CLI integration for SQLSpec migrations."""
+
+from contextlib import suppress
+from typing import TYPE_CHECKING
+
+from litestar.cli._utils import LitestarGroup
+
+from sqlspec.cli import add_migration_commands
+
+try:
+    import rich_click as click
+except ImportError:
+    import click  # type: ignore[no-redef]
+
+if TYPE_CHECKING:
+    from litestar import Litestar
+
+    from sqlspec.extensions.litestar.plugin import SQLSpec
+
+
+def get_database_migration_plugin(app: "Litestar") -> "SQLSpec":
+    """Retrieve the SQLSpec plugin from the Litestar application's plugins.
+
+    Args:
+        app: The Litestar application
+
+    Returns:
+        The SQLSpec plugin
+
+    Raises:
+        ImproperConfigurationError: If the SQLSpec plugin is not found
+    """
+    from sqlspec.exceptions import ImproperConfigurationError
+    from sqlspec.extensions.litestar.plugin import SQLSpec
+
+    with suppress(KeyError):
+        return app.plugins.get(SQLSpec)
+    msg = "Failed to initialize database migrations. The required SQLSpec plugin is missing."
+    raise ImproperConfigurationError(msg)
+
+
+@click.group(cls=LitestarGroup, name="database")
+def database_group(ctx: "click.Context") -> None:
+    """Manage SQLSpec database components."""
+    ctx.obj = {"app": ctx.obj, "configs": get_database_migration_plugin(ctx.obj.app).config}
+
+
+add_migration_commands(database_group)

sqlspec/extensions/litestar/plugin.py

@@ -47,6 +47,9 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
 
     def on_cli_init(self, cli: "Group") -> None:
         """Configure the CLI for use with SQLSpec."""
+        from sqlspec.extensions.litestar.cli import database_group
+
+        cli.add_command(database_group)
 
     def on_app_init(self, app_config: "AppConfig") -> "AppConfig":
         """Configure application for use with SQLSpec.

sqlspec/loader.py

@@ -40,7 +40,7 @@ def _normalize_query_name(name: str) -> str:
         name: Raw query name from SQL file
 
     Returns:
-        Normalized query name suitable as Python identifier
+        converted query name suitable as Python identifier
     """
     # Strip trailing non-alphanumeric characters (excluding underscore) and replace hyphens
     return TRIM_TRAILING_SPECIAL_CHARS.sub("", name).replace("-", "_")

sqlspec/migrations/__init__.py

@@ -0,0 +1,23 @@
+"""SQLSpec Migration Tool.
+
+A native migration system for SQLSpec that leverages the SQLFileLoader
+and driver architecture for database versioning.
+"""
+
+from sqlspec.migrations.commands import AsyncMigrationCommands, MigrationCommands, SyncMigrationCommands
+from sqlspec.migrations.runner import AsyncMigrationRunner, SyncMigrationRunner
+from sqlspec.migrations.tracker import AsyncMigrationTracker, SyncMigrationTracker
+from sqlspec.migrations.utils import create_migration_file, drop_all, get_author
+
+__all__ = (
+    "AsyncMigrationCommands",
+    "AsyncMigrationRunner",
+    "AsyncMigrationTracker",
+    "MigrationCommands",
+    "SyncMigrationCommands",
+    "SyncMigrationRunner",
+    "SyncMigrationTracker",
+    "create_migration_file",
+    "drop_all",
+    "get_author",
+)

sqlspec/migrations/base.py

@@ -0,0 +1,390 @@
+"""Base classes for SQLSpec migrations.
+
+This module provides abstract base classes for migration components.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Generic, Optional, TypeVar
+
+from sqlspec.loader import SQLFileLoader
+from sqlspec.statement.sql import SQL
+from sqlspec.utils.logging import get_logger
+
+__all__ = ("BaseMigrationCommands", "BaseMigrationRunner", "BaseMigrationTracker")
+
+
+logger = get_logger("migrations.base")
+
+# Type variables for generic driver and config types
+DriverT = TypeVar("DriverT")
+ConfigT = TypeVar("ConfigT")
+
+
+class BaseMigrationTracker(ABC, Generic[DriverT]):
+    """Base class for migration version tracking."""
+
+    def __init__(self, version_table_name: str = "ddl_migrations") -> None:
+        """Initialize the migration tracker.
+
+        Args:
+            version_table_name: Name of the table to track migrations.
+        """
+        self.version_table = version_table_name
+
+    def _get_create_table_sql(self) -> SQL:
+        """Get SQL for creating the tracking table.
+
+        Returns:
+            SQL object for table creation.
+        """
+        return SQL(
+            f"""
+            CREATE TABLE IF NOT EXISTS {self.version_table} (
+                version_num VARCHAR(32) PRIMARY KEY,
+                description TEXT,
+                applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                execution_time_ms INTEGER,
+                checksum VARCHAR(64),
+                applied_by VARCHAR(255)
+            )
+        """
+        )
+
+    def _get_current_version_sql(self) -> SQL:
+        """Get SQL for retrieving current version.
+
+        Returns:
+            SQL object for version query.
+        """
+        return SQL(f"SELECT version_num FROM {self.version_table} ORDER BY version_num DESC LIMIT 1")
+
+    def _get_applied_migrations_sql(self) -> SQL:
+        """Get SQL for retrieving all applied migrations.
+
+        Returns:
+            SQL object for migrations query.
+        """
+        return SQL(f"SELECT * FROM {self.version_table} ORDER BY version_num")
+
+    def _get_record_migration_sql(
+        self, version: str, description: str, execution_time_ms: int, checksum: str, applied_by: str
+    ) -> SQL:
+        """Get SQL for recording a migration.
+
+        Args:
+            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: User who applied the migration.
+
+        Returns:
+            SQL object for insert.
+        """
+        return SQL(
+            f"INSERT INTO {self.version_table} (version_num, description, execution_time_ms, checksum, applied_by) VALUES (?, ?, ?, ?, ?)",
+            version,
+            description,
+            execution_time_ms,
+            checksum,
+            applied_by,
+        )
+
+    def _get_remove_migration_sql(self, version: str) -> SQL:
+        """Get SQL for removing a migration record.
+
+        Args:
+            version: Version number to remove.
+
+        Returns:
+            SQL object for delete.
+        """
+        return SQL(f"DELETE FROM {self.version_table} WHERE version_num = ?", version)
+
+    @abstractmethod
+    def ensure_tracking_table(self, driver: DriverT) -> Any:
+        """Create the migration tracking table if it doesn't exist."""
+        ...
+
+    @abstractmethod
+    def get_current_version(self, driver: DriverT) -> Any:
+        """Get the latest applied migration version."""
+        ...
+
+    @abstractmethod
+    def get_applied_migrations(self, driver: DriverT) -> Any:
+        """Get all applied migrations in order."""
+        ...
+
+    @abstractmethod
+    def record_migration(
+        self, driver: DriverT, version: str, description: str, execution_time_ms: int, checksum: str
+    ) -> Any:
+        """Record a successfully applied migration."""
+        ...
+
+    @abstractmethod
+    def remove_migration(self, driver: DriverT, version: str) -> Any:
+        """Remove a migration record."""
+        ...
+
+
+class BaseMigrationRunner(ABC, Generic[DriverT]):
+    """Base class for migration execution."""
+
+    def __init__(self, migrations_path: Path) -> None:
+        """Initialize the migration runner.
+
+        Args:
+            migrations_path: Path to the directory containing migration files.
+        """
+        self.migrations_path = migrations_path
+        self.loader = SQLFileLoader()
+
+    def _extract_version(self, filename: str) -> Optional[str]:
+        """Extract version from filename (e.g., '0001_initial.sql' -> '0001').
+
+        Args:
+            filename: The migration filename.
+
+        Returns:
+            The extracted version string or None.
+        """
+        parts = filename.split("_", 1)
+        if parts and parts[0].isdigit():
+            return parts[0].zfill(4)
+        return None
+
+    def _calculate_checksum(self, content: str) -> str:
+        """Calculate MD5 checksum of migration content.
+
+        Args:
+            content: The migration file content.
+
+        Returns:
+            The MD5 checksum hex string.
+        """
+        import hashlib
+
+        return hashlib.md5(content.encode()).hexdigest()  # noqa: S324
+
+    def _get_migration_files_sync(self) -> "list[tuple[str, Path]]":
+        """Get all migration files sorted by version (sync version).
+
+        Returns:
+            List of tuples containing (version, file_path).
+        """
+        if not self.migrations_path.exists():
+            return []
+
+        migrations = []
+        for file_path in self.migrations_path.glob("*.sql"):
+            if file_path.name.startswith("."):
+                continue
+            version = self._extract_version(file_path.name)
+            if version:
+                migrations.append((version, file_path))
+
+        return sorted(migrations, key=lambda x: x[0])
+
+    def _load_migration_metadata(self, file_path: Path) -> "dict[str, Any]":
+        """Load migration metadata from file.
+
+        Args:
+            file_path: Path to the migration file.
+
+        Returns:
+            Dictionary containing migration metadata.
+        """
+        self.loader.clear_cache()
+        self.loader.load_sql(file_path)
+
+        # Read raw content for checksum
+        content = file_path.read_text()
+        checksum = self._calculate_checksum(content)
+
+        # Extract metadata
+        version = self._extract_version(file_path.name)
+        description = file_path.stem.split("_", 1)[1] if "_" in file_path.stem else ""
+
+        # Query names use versioned pattern
+        up_query = f"migrate-{version}-up"
+        down_query = f"migrate-{version}-down"
+
+        return {
+            "version": version,
+            "description": description,
+            "file_path": file_path,
+            "checksum": checksum,
+            "up_query": up_query,
+            "down_query": down_query,
+            "has_upgrade": self.loader.has_query(up_query),
+            "has_downgrade": self.loader.has_query(down_query),
+        }
+
+    def _get_migration_sql(self, migration: "dict[str, Any]", direction: str) -> Optional[SQL]:
+        """Get migration SQL for given direction.
+
+        Args:
+            migration: Migration metadata.
+            direction: Either 'up' or 'down'.
+
+        Returns:
+            SQL object for the migration.
+        """
+        query_key = f"{direction}_query"
+        has_key = f"has_{direction}grade"
+
+        if not migration.get(has_key):
+            if direction == "down":
+                logger.warning("Migration %s has no downgrade query", migration["version"])
+                return None
+            msg = f"Migration {migration['version']} has no upgrade query"
+            raise ValueError(msg)
+
+        return self.loader.get_sql(migration[query_key])
+
+    @abstractmethod
+    def get_migration_files(self) -> Any:
+        """Get all migration files sorted by version."""
+        ...
+
+    @abstractmethod
+    def load_migration(self, file_path: Path) -> Any:
+        """Load a migration file and extract its components."""
+        ...
+
+    @abstractmethod
+    def execute_upgrade(self, driver: DriverT, migration: "dict[str, Any]") -> Any:
+        """Execute an upgrade migration."""
+        ...
+
+    @abstractmethod
+    def execute_downgrade(self, driver: DriverT, migration: "dict[str, Any]") -> Any:
+        """Execute a downgrade migration."""
+        ...
+
+    @abstractmethod
+    def load_all_migrations(self) -> Any:
+        """Load all migrations into a single namespace for bulk operations."""
+        ...
+
+
+class BaseMigrationCommands(ABC, Generic[ConfigT, DriverT]):
+    """Base class for migration commands."""
+
+    def __init__(self, config: ConfigT) -> None:
+        """Initialize migration commands.
+
+        Args:
+            config: The SQLSpec configuration.
+        """
+        self.config = config
+
+        # Get migration settings from config
+        migration_config = getattr(self.config, "migration_config", {})
+        if migration_config is None:
+            migration_config = {}
+
+        self.version_table = migration_config.get("version_table_name", "sqlspec_migrations")
+        self.migrations_path = Path(migration_config.get("script_location", "migrations"))
+
+    def _get_init_readme_content(self) -> str:
+        """Get the README content for migration directory initialization.
+
+        Returns:
+            The README markdown content.
+        """
+        return """# SQLSpec Migrations
+
+This directory contains database migration files.
+
+## File Format
+
+Migration files use SQLFileLoader's named query syntax with versioned names:
+
+```sql
+-- name: migrate-0001-up
+CREATE TABLE example (
+    id INTEGER PRIMARY KEY,
+    name TEXT NOT NULL
+);
+
+-- name: migrate-0001-down
+DROP TABLE example;
+```
+
+## Naming Conventions
+
+### File Names
+
+Format: `{version}_{description}.sql`
+
+- Version: Zero-padded 4-digit number (0001, 0002, etc.)
+- Description: Brief description using underscores
+- Example: `0001_create_users_table.sql`
+
+### Query Names
+
+- Upgrade: `migrate-{version}-up`
+- Downgrade: `migrate-{version}-down`
+
+This naming ensures proper sorting and avoids conflicts when loading multiple files.
+"""
+
+    def init_directory(self, directory: str, package: bool = True) -> None:
+        """Initialize migration directory structure (sync implementation).
+
+        Args:
+            directory: Directory to initialize migrations in.
+            package: Whether to create __init__.py file.
+        """
+        from rich.console import Console
+
+        console = Console()
+
+        migrations_dir = Path(directory)
+        migrations_dir.mkdir(parents=True, exist_ok=True)
+
+        if package:
+            (migrations_dir / "__init__.py").touch()
+
+        # Create README
+        readme = migrations_dir / "README.md"
+        readme.write_text(self._get_init_readme_content())
+
+        # Create .gitkeep for empty directory
+        (migrations_dir / ".gitkeep").touch()
+
+        console.print(f"[green]Initialized migrations in {directory}[/]")
+
+    @abstractmethod
+    def init(self, directory: str, package: bool = True) -> Any:
+        """Initialize migration directory structure."""
+        ...
+
+    @abstractmethod
+    def current(self, verbose: bool = False) -> Any:
+        """Show current migration version."""
+        ...
+
+    @abstractmethod
+    def upgrade(self, revision: str = "head") -> Any:
+        """Upgrade to a target revision."""
+        ...
+
+    @abstractmethod
+    def downgrade(self, revision: str = "-1") -> Any:
+        """Downgrade to a target revision."""
+        ...
+
+    @abstractmethod
+    def stamp(self, revision: str) -> Any:
+        """Mark database as being at a specific revision without running migrations."""
+        ...
+
+    @abstractmethod
+    def revision(self, message: str) -> Any:
+        """Create a new migration file."""
+        ...