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

sqlspec/builder/_insert.py

@@ -1,7 +1,7 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""INSERT statement builder.
 
-This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation.
+Provides a fluent interface for building SQL INSERT queries with
+parameter binding and validation.
 """
 
 from typing import TYPE_CHECKING, Any, Final, Optional
@@ -31,8 +31,7 @@ ERR_MSG_EXPRESSION_NOT_INITIALIZED: Final[str] = "Internal error: base expressio
 class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSelectMixin, InsertIntoClauseMixin):
     """Builder for INSERT statements.
 
-    This builder facilitates the construction of SQL INSERT queries
-    in a safe and dialect-agnostic manner with automatic parameter binding.
+    Constructs SQL INSERT queries with parameter binding and validation.
     """
 
     __slots__ = ("_columns", "_table", "_values_added_count")
@@ -316,8 +315,8 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
 class ConflictBuilder:
     """Builder for ON CONFLICT clauses in INSERT statements.
 
-    This builder provides a fluent interface for constructing conflict resolution
-    clauses using PostgreSQL-style syntax, which SQLGlot can transpile to other dialects.
+    Constructs conflict resolution clauses using PostgreSQL-style syntax,
+    which SQLGlot can transpile to other dialects.
     """
 
     __slots__ = ("_columns", "_insert_builder")

sqlspec/builder/_merge.py

@@ -1,7 +1,7 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""MERGE statement builder.
 
-This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation.
+Provides a fluent interface for building SQL MERGE queries with
+parameter binding and validation.
 """
 
 from typing import Any, Optional
@@ -33,8 +33,8 @@ class Merge(
 ):
     """Builder for MERGE statements.
 
-    This builder provides a fluent interface for constructing SQL MERGE statements
-    (also known as UPSERT in some databases) with automatic parameter binding and validation.
+    Constructs SQL MERGE statements (also known as UPSERT in some databases)
+    with parameter binding and validation.
     """
 
     __slots__ = ()

sqlspec/builder/_parsing_utils.py

@@ -1,7 +1,7 @@
-"""Centralized parsing utilities for SQLSpec builders.
+"""Parsing utilities for SQL builders.
 
-This module provides common parsing functions to handle complex SQL expressions
-that users might pass as strings to various builder methods.
+Provides common parsing functions to handle SQL expressions
+passed as strings to builder methods.
 """
 
 import contextlib

sqlspec/builder/_select.py

@@ -1,7 +1,7 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""SELECT statement builder.
 
-This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation.
+Provides a fluent interface for building SQL SELECT queries with
+parameter binding and validation.
 """
 
 import re
@@ -44,9 +44,10 @@ class Select(
     PivotClauseMixin,
     UnpivotClauseMixin,
 ):
-    """Type-safe builder for SELECT queries with schema/model integration.
+    """Builder for SELECT queries.
 
-    This builder provides a fluent, safe interface for constructing SQL SELECT statements.
+    Provides a fluent interface for constructing SQL SELECT statements
+    with parameter binding and validation.
 
     Example:
         >>> class User(BaseModel):

sqlspec/builder/_update.py

@@ -1,7 +1,7 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""UPDATE statement builder.
 
-This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation.
+Provides a fluent interface for building SQL UPDATE queries with
+parameter binding and validation.
 """
 
 from typing import TYPE_CHECKING, Any, Optional, Union
@@ -36,8 +36,7 @@ class Update(
 ):
     """Builder for UPDATE statements.
 
-    This builder provides a fluent interface for constructing SQL UPDATE statements
-    with automatic parameter binding and validation.
+    Constructs SQL UPDATE statements with parameter binding and validation.
 
     Example:
         ```python

sqlspec/builder/mixins/_cte_and_set_ops.py

@@ -1,4 +1,8 @@
-"""CTE (Common Table Expression) and Set Operations mixins for SQL builders."""
+"""CTE and set operation mixins.
+
+Provides mixins for Common Table Expressions (WITH clause) and
+set operations (UNION, INTERSECT, EXCEPT).
+"""
 
 from typing import Any, Optional, Union
 

sqlspec/builder/mixins/_delete_operations.py

@@ -1,4 +1,8 @@
-"""Delete operation mixins for SQL builders."""
+"""DELETE operation mixins.
+
+Provides mixins for DELETE statement functionality including
+FROM clause specification.
+"""
 
 from typing import Optional
 

sqlspec/builder/mixins/_insert_operations.py

@@ -1,4 +1,8 @@
-"""Insert operation mixins for SQL builders."""
+"""INSERT operation mixins.
+
+Provides mixins for INSERT statement functionality including
+INTO clauses, VALUES clauses, and INSERT FROM SELECT operations.
+"""
 
 from collections.abc import Sequence
 from typing import Any, Optional, TypeVar, Union

sqlspec/builder/mixins/_join_operations.py

@@ -1,3 +1,8 @@
+"""JOIN operation mixins.
+
+Provides mixins for JOIN operations in SELECT statements.
+"""
+
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 from mypy_extensions import trait

sqlspec/builder/mixins/_merge_operations.py

@@ -1,4 +1,8 @@
-"""Merge operation mixins for SQL builders."""
+"""MERGE operation mixins.
+
+Provides mixins for MERGE statement functionality including INTO,
+USING, ON, WHEN MATCHED, and WHEN NOT MATCHED clauses.
+"""
 
 from typing import Any, Optional, Union
 

sqlspec/builder/mixins/_order_limit_operations.py

@@ -1,4 +1,8 @@
-"""Order, Limit, Offset and Returning operations mixins for SQL builders."""
+"""ORDER BY, LIMIT, OFFSET, and RETURNING clause mixins.
+
+Provides mixins for query result ordering, limiting, and result
+returning functionality.
+"""
 
 from typing import TYPE_CHECKING, Optional, Union, cast
 

sqlspec/builder/mixins/_pivot_operations.py

@@ -1,4 +1,7 @@
-"""Pivot and Unpivot operations mixins for SQL builders."""
+"""PIVOT and UNPIVOT operation mixins.
+
+Provides mixins for PIVOT and UNPIVOT operations in SELECT statements.
+"""
 
 from typing import TYPE_CHECKING, Optional, Union, cast
 

sqlspec/builder/mixins/_select_operations.py

@@ -1,4 +1,8 @@
-"""SELECT clause mixins consolidated into a single module."""
+"""SELECT clause mixins.
+
+Provides mixins for SELECT statement functionality including column selection,
+CASE expressions, subqueries, and window functions.
+"""
 
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
 

sqlspec/builder/mixins/_update_operations.py

@@ -1,4 +1,8 @@
-"""Update operation mixins for SQL builders."""
+"""UPDATE operation mixins.
+
+Provides mixins for UPDATE statement functionality including
+table specification, SET clauses, and FROM clauses.
+"""
 
 from collections.abc import Mapping
 from typing import Any, Optional, Union, cast

sqlspec/builder/mixins/_where_clause.py

@@ -1,5 +1,9 @@
 # ruff: noqa: PLR2004
-"""Consolidated WHERE and HAVING clause mixins."""
+"""WHERE and HAVING clause mixins.
+
+Provides mixins for WHERE and HAVING clause functionality with
+parameter binding and various condition operators.
+"""
 
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
 

sqlspec/cli.py

@@ -1,3 +1,4 @@
+# ruff: noqa: C901
 import sys
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
@@ -99,6 +100,15 @@ def add_migration_commands(database_group: Optional["Group"] = None) -> "Group":
         show_default=True,
         is_flag=True,
     )
+    include_option = click.option(
+        "--include", multiple=True, help="Include only specific configurations (can be used multiple times)"
+    )
+    exclude_option = click.option(
+        "--exclude", multiple=True, help="Exclude specific configurations (can be used multiple times)"
+    )
+    dry_run_option = click.option(
+        "--dry-run", is_flag=True, default=False, help="Show what would be executed without making changes"
+    )
 
     def get_config_by_bind_key(
         ctx: "click.Context", bind_key: Optional[str]
@@ -114,35 +124,180 @@ def add_migration_commands(database_group: Optional["Group"] = None) -> "Group":
         """
         configs = ctx.obj["configs"]
         if bind_key is None:
-            return cast("Union[AsyncDatabaseConfig[Any, Any, Any], SyncDatabaseConfig[Any, Any, Any]]", configs[0])
+            config = configs[0]
+        else:
+            config = None
+            for cfg in configs:
+                config_name = getattr(cfg, "name", None) or getattr(cfg, "bind_key", None)
+                if config_name == bind_key:
+                    config = cfg
+                    break
+
+            if config is None:
+                console.print(f"[red]No config found for bind key: {bind_key}[/]")
+                sys.exit(1)
+
+        # Extract the actual config from DatabaseConfig wrapper if needed
+        from sqlspec.extensions.litestar.config import DatabaseConfig
+
+        if isinstance(config, DatabaseConfig):
+            config = config.config
+
+        return cast("Union[AsyncDatabaseConfig[Any, Any, Any], SyncDatabaseConfig[Any, Any, Any]]", config)
+
+    def get_configs_with_migrations(ctx: "click.Context", enabled_only: bool = False) -> "list[tuple[str, Any]]":
+        """Get all configurations that have migrations enabled.
+
+        Args:
+            ctx: The click context.
+            enabled_only: If True, only return configs with enabled=True.
+
+        Returns:
+            List of tuples (config_name, config) for configs with migrations enabled.
+        """
+        configs = ctx.obj["configs"]
+        migration_configs = []
+
+        from sqlspec.extensions.litestar.config import DatabaseConfig
 
         for config in configs:
-            config_name = getattr(config, "name", None) or getattr(config, "bind_key", None)
-            if config_name == bind_key:
-                return cast("Union[AsyncDatabaseConfig[Any, Any, Any], SyncDatabaseConfig[Any, Any, Any]]", config)
+            # Extract the actual config from DatabaseConfig wrapper if needed
+            actual_config = config.config if isinstance(config, DatabaseConfig) else config
+
+            migration_config = getattr(actual_config, "migration_config", None)
+            if migration_config:
+                enabled = migration_config.get("enabled", True)
+                if not enabled_only or enabled:
+                    config_name = (
+                        getattr(actual_config, "name", None)
+                        or getattr(actual_config, "bind_key", None)
+                        or str(type(actual_config).__name__)
+                    )
+                    migration_configs.append((config_name, actual_config))
+
+        return migration_configs
+
+    def filter_configs(
+        configs: "list[tuple[str, Any]]", include: "tuple[str, ...]", exclude: "tuple[str, ...]"
+    ) -> "list[tuple[str, Any]]":
+        """Filter configuration list based on include/exclude criteria.
+
+        Args:
+            configs: List of (config_name, config) tuples.
+            include: Config names to include (empty means include all).
+            exclude: Config names to exclude.
+
+        Returns:
+            Filtered list of configurations.
+        """
+        filtered = configs
+        if include:
+            filtered = [(name, config) for name, config in filtered if name in include]
+        if exclude:
+            filtered = [(name, config) for name, config in filtered if name not in exclude]
+        return filtered
+
+    def process_multiple_configs(
+        ctx: "click.Context",
+        bind_key: Optional[str],
+        include: "tuple[str, ...]",
+        exclude: "tuple[str, ...]",
+        dry_run: bool,
+        operation_name: str,
+    ) -> "Optional[list[tuple[str, Any]]]":
+        """Process configuration selection for multi-config operations.
+
+        Args:
+            ctx: Click context.
+            bind_key: Specific bind key to target.
+            include: Config names to include.
+            exclude: Config names to exclude.
+            dry_run: Whether this is a dry run.
+            operation_name: Name of the operation for display.
+
+        Returns:
+            List of (config_name, config) tuples to process, or None for single config mode.
+        """
+        # If specific bind_key requested, use single config mode
+        if bind_key and not include and not exclude:
+            return None
+
+        # Get enabled configs by default, all configs if include/exclude specified
+        enabled_only = not include and not exclude
+        migration_configs = get_configs_with_migrations(ctx, enabled_only=enabled_only)
+
+        # If only one config and no filtering, use single config mode
+        if len(migration_configs) <= 1 and not include and not exclude:
+            return None
+
+        # Apply filtering
+        configs_to_process = filter_configs(migration_configs, include, exclude)
+
+        if not configs_to_process:
+            console.print("[yellow]No configurations match the specified criteria.[/]")
+            return []
 
-        console.print(f"[red]No config found for bind key: {bind_key}[/]")
-        sys.exit(1)
+        # Show what will be processed
+        if dry_run:
+            console.print(f"[blue]Dry run: Would {operation_name} {len(configs_to_process)} configuration(s)[/]")
+            for config_name, _ in configs_to_process:
+                console.print(f"  • {config_name}")
+            return []
+
+        return configs_to_process
 
     @database_group.command(name="show-current-revision", help="Shows the current revision for the database.")
     @bind_key_option
     @verbose_option
-    def show_database_revision(bind_key: Optional[str], verbose: bool) -> None:  # pyright: ignore[reportUnusedFunction]
+    @include_option
+    @exclude_option
+    def show_database_revision(  # pyright: ignore[reportUnusedFunction]
+        bind_key: Optional[str], verbose: bool, include: "tuple[str, ...]", exclude: "tuple[str, ...]"
+    ) -> None:
         """Show current database revision."""
         from sqlspec.migrations.commands import MigrationCommands
 
         ctx = click.get_current_context()
-        console.rule("[yellow]Listing current revision[/]", align="left")
-        sqlspec_config = get_config_by_bind_key(ctx, bind_key)
-        migration_commands = MigrationCommands(config=sqlspec_config)
-        migration_commands.current(verbose=verbose)
+
+        # Check if this is a multi-config operation
+        configs_to_process = process_multiple_configs(
+            ctx, bind_key, include, exclude, dry_run=False, operation_name="show current revision"
+        )
+
+        if configs_to_process is not None:
+            if not configs_to_process:
+                return
+
+            console.rule("[yellow]Listing current revisions for all configurations[/]", align="left")
+
+            for config_name, config in configs_to_process:
+                console.print(f"\n[blue]Configuration: {config_name}[/]")
+                try:
+                    migration_commands = MigrationCommands(config=config)
+                    migration_commands.current(verbose=verbose)
+                except Exception as e:
+                    console.print(f"[red]✗ Failed to get current revision for {config_name}: {e}[/]")
+        else:
+            # Single config operation
+            console.rule("[yellow]Listing current revision[/]", align="left")
+            sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+            migration_commands = MigrationCommands(config=sqlspec_config)
+            migration_commands.current(verbose=verbose)
 
     @database_group.command(name="downgrade", help="Downgrade database to a specific revision.")
     @bind_key_option
     @no_prompt_option
+    @include_option
+    @exclude_option
+    @dry_run_option
     @click.argument("revision", type=str, default="-1")
     def downgrade_database(  # pyright: ignore[reportUnusedFunction]
-        bind_key: Optional[str], revision: str, no_prompt: bool
+        bind_key: Optional[str],
+        revision: str,
+        no_prompt: bool,
+        include: "tuple[str, ...]",
+        exclude: "tuple[str, ...]",
+        dry_run: bool,
     ) -> None:
         """Downgrade the database to the latest revision."""
         from rich.prompt import Confirm
@@ -150,23 +305,59 @@ def add_migration_commands(database_group: Optional["Group"] = None) -> "Group":
         from sqlspec.migrations.commands import MigrationCommands
 
         ctx = click.get_current_context()
-        console.rule("[yellow]Starting database downgrade process[/]", align="left")
-        input_confirmed = (
-            True
-            if no_prompt
-            else Confirm.ask(f"Are you sure you want to downgrade the database to the `{revision}` revision?")
+
+        # Check if this is a multi-config operation
+        configs_to_process = process_multiple_configs(
+            ctx, bind_key, include, exclude, dry_run=dry_run, operation_name=f"downgrade to {revision}"
         )
-        if input_confirmed:
-            sqlspec_config = get_config_by_bind_key(ctx, bind_key)
-            migration_commands = MigrationCommands(config=sqlspec_config)
-            migration_commands.downgrade(revision=revision)
+
+        if configs_to_process is not None:
+            if not configs_to_process:
+                return
+
+            if not no_prompt and not Confirm.ask(
+                f"[bold]Are you sure you want to downgrade {len(configs_to_process)} configuration(s) to revision {revision}?[/]"
+            ):
+                console.print("[yellow]Operation cancelled.[/]")
+                return
+
+            console.rule("[yellow]Starting multi-configuration downgrade process[/]", align="left")
+
+            for config_name, config in configs_to_process:
+                console.print(f"[blue]Downgrading configuration: {config_name}[/]")
+                try:
+                    migration_commands = MigrationCommands(config=config)
+                    migration_commands.downgrade(revision=revision)
+                    console.print(f"[green]✓ Successfully downgraded: {config_name}[/]")
+                except Exception as e:
+                    console.print(f"[red]✗ Failed to downgrade {config_name}: {e}[/]")
+        else:
+            # Single config operation
+            console.rule("[yellow]Starting database downgrade process[/]", align="left")
+            input_confirmed = (
+                True
+                if no_prompt
+                else Confirm.ask(f"Are you sure you want to downgrade the database to the `{revision}` revision?")
+            )
+            if input_confirmed:
+                sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+                migration_commands = MigrationCommands(config=sqlspec_config)
+                migration_commands.downgrade(revision=revision)
 
     @database_group.command(name="upgrade", help="Upgrade database to a specific revision.")
     @bind_key_option
     @no_prompt_option
+    @include_option
+    @exclude_option
+    @dry_run_option
     @click.argument("revision", type=str, default="head")
     def upgrade_database(  # pyright: ignore[reportUnusedFunction]
-        bind_key: Optional[str], revision: str, no_prompt: bool
+        bind_key: Optional[str],
+        revision: str,
+        no_prompt: bool,
+        include: "tuple[str, ...]",
+        exclude: "tuple[str, ...]",
+        dry_run: bool,
     ) -> None:
         """Upgrade the database to the latest revision."""
         from rich.prompt import Confirm
@@ -174,16 +365,44 @@ def add_migration_commands(database_group: Optional["Group"] = None) -> "Group":
         from sqlspec.migrations.commands import MigrationCommands
 
         ctx = click.get_current_context()
-        console.rule("[yellow]Starting database upgrade process[/]", align="left")
-        input_confirmed = (
-            True
-            if no_prompt
-            else Confirm.ask(f"[bold]Are you sure you want migrate the database to the `{revision}` revision?[/]")
+
+        # Check if this is a multi-config operation
+        configs_to_process = process_multiple_configs(
+            ctx, bind_key, include, exclude, dry_run, operation_name=f"upgrade to {revision}"
         )
-        if input_confirmed:
-            sqlspec_config = get_config_by_bind_key(ctx, bind_key)
-            migration_commands = MigrationCommands(config=sqlspec_config)
-            migration_commands.upgrade(revision=revision)
+
+        if configs_to_process is not None:
+            if not configs_to_process:
+                return
+
+            if not no_prompt and not Confirm.ask(
+                f"[bold]Are you sure you want to upgrade {len(configs_to_process)} configuration(s) to revision {revision}?[/]"
+            ):
+                console.print("[yellow]Operation cancelled.[/]")
+                return
+
+            console.rule("[yellow]Starting multi-configuration upgrade process[/]", align="left")
+
+            for config_name, config in configs_to_process:
+                console.print(f"[blue]Upgrading configuration: {config_name}[/]")
+                try:
+                    migration_commands = MigrationCommands(config=config)
+                    migration_commands.upgrade(revision=revision)
+                    console.print(f"[green]✓ Successfully upgraded: {config_name}[/]")
+                except Exception as e:
+                    console.print(f"[red]✗ Failed to upgrade {config_name}: {e}[/]")
+        else:
+            # Single config operation
+            console.rule("[yellow]Starting database upgrade process[/]", align="left")
+            input_confirmed = (
+                True
+                if no_prompt
+                else Confirm.ask(f"[bold]Are you sure you want migrate the database to the `{revision}` revision?[/]")
+            )
+            if input_confirmed:
+                sqlspec_config = get_config_by_bind_key(ctx, bind_key)
+                migration_commands = MigrationCommands(config=sqlspec_config)
+                migration_commands.upgrade(revision=revision)
 
     @database_group.command(help="Stamp the revision table with the given revision")
     @click.argument("revision", type=str)
@@ -217,10 +436,14 @@ def add_migration_commands(database_group: Optional["Group"] = None) -> "Group":
         )
         if input_confirmed:
             configs = [get_config_by_bind_key(ctx, bind_key)] if bind_key is not None else ctx.obj["configs"]
+            from sqlspec.extensions.litestar.config import DatabaseConfig
+
             for config in configs:
-                migration_config = getattr(config, "migration_config", {})
+                # Extract the actual config from DatabaseConfig wrapper if needed
+                actual_config = config.config if isinstance(config, DatabaseConfig) else config
+                migration_config = getattr(actual_config, "migration_config", {})
                 directory = migration_config.get("script_location", "migrations") if directory is None else directory
-                migration_commands = MigrationCommands(config=config)
+                migration_commands = MigrationCommands(config=actual_config)
                 migration_commands.init(directory=cast("str", directory), package=package)
 
     @database_group.command(name="make-migrations", help="Create a new migration revision.")
@@ -244,4 +467,29 @@ def add_migration_commands(database_group: Optional["Group"] = None) -> "Group":
         migration_commands = MigrationCommands(config=sqlspec_config)
         migration_commands.revision(message=message)
 
+    @database_group.command(name="show-config", help="Show all configurations with migrations enabled.")
+    def show_config() -> None:  # pyright: ignore[reportUnusedFunction]
+        """Show and display all configurations with migrations enabled."""
+        from rich.table import Table
+
+        ctx = click.get_current_context()
+        migration_configs = get_configs_with_migrations(ctx)
+
+        if not migration_configs:
+            console.print("[yellow]No configurations with migrations detected.[/]")
+            return
+
+        table = Table(title="Migration Configurations")
+        table.add_column("Configuration Name", style="cyan")
+        table.add_column("Migration Path", style="blue")
+        table.add_column("Status", style="green")
+
+        for config_name, config in migration_configs:
+            migration_config = getattr(config, "migration_config", {})
+            script_location = migration_config.get("script_location", "migrations")
+            table.add_row(config_name, script_location, "Migration Enabled")
+
+        console.print(table)
+        console.print(f"[blue]Found {len(migration_configs)} configuration(s) with migrations enabled.[/]")
+
     return database_group