"""Command-line interface utilities and migration commands for Advanced Alchemy."""
import asyncio
import inspect
import sys
from collections.abc import Callable, Coroutine, Sequence
from concurrent.futures import ThreadPoolExecutor
from importlib import import_module
from pathlib import Path
from types import ModuleType
from typing import TYPE_CHECKING, Any, Optional, Union, cast
if TYPE_CHECKING:
from alembic.migration import MigrationContext
from alembic.operations.ops import MigrationScript, UpgradeOps
from click import Group
from advanced_alchemy.config import SQLAlchemyAsyncConfig, SQLAlchemySyncConfig
from advanced_alchemy.utils.fixtures import FixtureCompression, FixtureFormat
__all__ = (
"add_migration_commands",
"discover_config_from_pyproject",
"find_pyproject_toml",
"get_alchemy_group",
"parse_pyproject_config",
"resolve_config_async",
"resolve_config_sync",
)
_PYPROJECT_TOOL_SECTIONS = ("advanced-alchemy", "advanced_alchemy", "alchemy")
[docs]
def discover_config_from_pyproject() -> Optional[str]:
"""Find and parse ``pyproject.toml`` for Advanced Alchemy CLI configuration.
Walks upward from the current working directory to locate ``pyproject.toml``
and parses ``[tool.advanced-alchemy]`` (or ``[tool.advanced_alchemy]`` /
``[tool.alchemy]``) for the ``config`` key.
Returns:
Configured path string (comma-separated when configured as a list), or
``None`` when not found.
"""
pyproject_path = find_pyproject_toml()
if pyproject_path is None:
return None
return parse_pyproject_config(pyproject_path)
[docs]
def find_pyproject_toml() -> Optional[Path]:
"""Walk the filesystem upward from ``Path.cwd()`` to find ``pyproject.toml``.
Stops at a ``.git`` directory boundary (repository root) or the filesystem root.
Returns:
Path to ``pyproject.toml``, or ``None`` if not found.
"""
current = Path.cwd()
while True:
pyproject = current / "pyproject.toml"
if pyproject.exists():
return pyproject
if (current / ".git").exists():
return None
if current == current.parent:
return None
current = current.parent
[docs]
def parse_pyproject_config(pyproject_path: Path) -> Optional[str]:
"""Parse ``pyproject.toml`` for Advanced Alchemy CLI configuration.
Checks ``[tool.advanced-alchemy]``, ``[tool.advanced_alchemy]``, and
``[tool.alchemy]`` in order for a ``config`` entry.
Args:
pyproject_path: Path to the ``pyproject.toml`` file.
Returns:
Config path(s) as a string (converting a list of strings to a
comma-separated string), or ``None`` if no config is defined.
Raises:
ValueError: If the ``pyproject.toml`` file cannot be parsed or the
``config`` value is not a string or list of strings.
"""
try:
data = _load_toml(pyproject_path)
except Exception as e:
msg = f"Failed to parse {pyproject_path}: {e}"
raise ValueError(msg) from e
raw_tool_section = data.get("tool", {})
if not isinstance(raw_tool_section, dict):
return None
tool_section = cast("dict[str, Any]", raw_tool_section)
for section_name in _PYPROJECT_TOOL_SECTIONS:
raw_alchemy_section = tool_section.get(section_name)
if not isinstance(raw_alchemy_section, dict) or "config" not in raw_alchemy_section:
continue
alchemy_section = cast("dict[str, Any]", raw_alchemy_section)
config: Any = alchemy_section.get("config")
if config is None:
return None
if isinstance(config, str):
return config
if isinstance(config, list):
config_items = cast("Sequence[Any]", config)
if not all(isinstance(item, str) for item in config_items):
msg = f"Invalid [tool.{section_name}].config in {pyproject_path}: list items must be strings"
raise ValueError(msg)
return ",".join(cast("Sequence[str]", config_items))
config_type_name = type(cast("object", config)).__name__
msg = (
f"Invalid [tool.{section_name}].config in {pyproject_path}: "
f"must be string or list of strings, got {config_type_name}"
)
raise ValueError(msg)
return None
[docs]
async def resolve_config_async(
config_path: str,
) -> "Union[list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]], SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]":
"""Resolve configuration asynchronously from a dotted or colon-separated path.
Supports direct config instances, sequences of configs, wrapper objects exposing
``.config`` (such as ``SQLAlchemyInitPlugin`` or ``AdvancedAlchemy``), synchronous
factory callables, and asynchronous coroutine factories.
Args:
config_path: ``module.attribute`` or ``module:attribute`` path to a config
object or factory callable.
Returns:
A resolved config instance or list of config instances.
Raises:
ImproperConfigurationError: If importing, executing, or validating the
configuration fails.
"""
from advanced_alchemy.exceptions import ImproperConfigurationError
try:
config_obj = _import_config_target(config_path)
except ImportError as e:
msg = f"Failed to import config from path '{config_path}': {e}"
raise ImproperConfigurationError(msg) from e
if not callable(config_obj) or isinstance(config_obj, type):
return _validate_config_result(config_obj, config_path)
try:
if inspect.iscoroutinefunction(config_obj):
result = await config_obj()
else:
result = await asyncio.to_thread(config_obj)
if inspect.isawaitable(result):
result = await result
except Exception as e:
msg = f"Failed to execute callable config '{config_path}': {e}"
raise ImproperConfigurationError(msg) from e
return _validate_config_result(result, config_path)
[docs]
def resolve_config_sync(
config_path: str,
) -> "Union[list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]], SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]":
"""Resolve configuration synchronously from a dotted or colon-separated path.
Supports direct config instances, sequences of configs, wrapper objects exposing
``.config`` (such as ``SQLAlchemyInitPlugin`` or ``AdvancedAlchemy``), synchronous
factory callables, and asynchronous coroutine factories.
Args:
config_path: ``module.attribute`` or ``module:attribute`` path to a config
object or factory callable.
Returns:
A resolved config instance or list of config instances.
Raises:
ImproperConfigurationError: If importing, executing, or validating the
configuration fails.
"""
from advanced_alchemy.exceptions import ImproperConfigurationError
try:
config_obj = _import_config_target(config_path)
except ImportError as e:
msg = f"Failed to import config from path '{config_path}': {e}"
raise ImproperConfigurationError(msg) from e
if not callable(config_obj) or isinstance(config_obj, type):
return _validate_config_result(config_obj, config_path)
try:
if inspect.iscoroutinefunction(config_obj):
result = _run_coroutine_sync(config_obj())
else:
result = config_obj()
if inspect.isawaitable(result):
result = _run_coroutine_sync(cast("Coroutine[Any, Any, Any]", result))
except Exception as e:
msg = f"Failed to execute callable config '{config_path}': {e}"
raise ImproperConfigurationError(msg) from e
return _validate_config_result(result, config_path)
[docs]
def get_alchemy_group() -> "Group":
"""Get the Advanced Alchemy CLI group.
Raises:
MissingDependencyError: If the ``click`` package is not installed.
Returns:
The Advanced Alchemy CLI group.
"""
from advanced_alchemy.exceptions import MissingDependencyError
from advanced_alchemy.utils.cli_tools import click, group
if click is None: # pragma: no cover
raise MissingDependencyError(package="click", install_package="cli")
config_option = _config_option(click)
validate_config_option = _validate_config_option(click)
@group(name="alchemy") # pyright: ignore
@config_option
@validate_config_option
@click.pass_context
def alchemy_group(ctx: "click.Context") -> None:
"""Advanced Alchemy CLI commands."""
ctx.ensure_object(dict)
return alchemy_group
[docs]
def add_migration_commands(database_group: Optional["Group"] = None) -> "Group": # noqa: C901, PLR0915
"""Add migration commands to the database group.
Args:
database_group: The database group to add the commands to.
Returns:
The database group with the migration commands added.
"""
from advanced_alchemy.utils.cli_tools import BYTE_SIZE, argument, click, option
console = _ConsoleProxy()
if database_group is None:
database_group = get_alchemy_group()
config_option = _config_option(click)
validate_config_option = _validate_config_option(click)
bind_key_option = option(
"--bind-key",
help="Specify which SQLAlchemy config to use by bind key",
type=str,
default=None,
)
verbose_option = option(
"--verbose",
help="Enable verbose output.",
type=bool,
default=False,
is_flag=True,
)
no_prompt_option = option(
"--no-prompt",
help="Do not prompt for confirmation before executing the command.",
type=bool,
default=False,
required=False,
show_default=True,
is_flag=True,
)
def get_config_by_bind_key(
ctx: "click.Context", bind_key: Optional[str]
) -> "Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]":
"""Get the SQLAlchemy config for the specified bind key.
Args:
ctx: The click context.
bind_key: The bind key to get the config for.
Returns:
The SQLAlchemy config for the specified bind key.
"""
configs = _resolve_alchemy_configs(ctx)
if bind_key is None:
return configs[0]
for config in configs:
if config.bind_key == bind_key:
return config
console.print(f"[red]No config found for bind key: {bind_key}[/]")
sys.exit(1)
@database_group.command(
name="show-config",
help="Show all configurations with migrations enabled.",
)
@config_option
@validate_config_option
@bind_key_option
def show_config(bind_key: Optional[str] = None) -> None: # pyright: ignore[reportUnusedFunction]
"""Show and display all loaded configurations."""
from rich.table import Table
ctx = cast("click.Context", click.get_current_context())
configs = [get_config_by_bind_key(ctx, bind_key)] if bind_key is not None else _resolve_alchemy_configs(ctx)
if not configs: # pragma: no cover
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 cfg in configs:
config_name = cfg.bind_key or "default"
script_location = getattr(cfg.alembic_config, "script_location", "migrations")
table.add_row(str(config_name), str(script_location), "Migration Enabled")
console.print(table)
console.print(f"[blue]Found {len(configs)} configuration(s) with migrations enabled.[/]")
@database_group.command(
name="show-current-revision",
help="Shows the current revision for the database.",
)
@config_option
@validate_config_option
@bind_key_option
@verbose_option
def show_database_revision(bind_key: Optional[str], verbose: bool) -> None: # pyright: ignore[reportUnusedFunction]
"""Show current database revision."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Listing current revision[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.current(verbose=verbose)
@database_group.command(
name="downgrade",
help="Downgrade database to a specific revision.",
)
@config_option
@validate_config_option
@bind_key_option
@option("--sql", type=bool, help="Generate SQL output for offline migrations.", default=False, is_flag=True)
@option(
"--tag",
help="an arbitrary 'tag' that can be intercepted by custom env.py scripts via the .EnvironmentContext.get_tag_argument method.",
type=str,
default=None,
)
@no_prompt_option
@argument(
"revision",
type=str,
default="-1",
)
def downgrade_database( # pyright: ignore[reportUnusedFunction]
bind_key: Optional[str], revision: str, sql: bool, tag: Optional[str], no_prompt: bool
) -> None:
"""Downgrade the database to the latest revision."""
from rich.prompt import Confirm
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
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:
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.downgrade(revision=revision, sql=sql, tag=tag)
@database_group.command(
name="upgrade",
help="Upgrade database to a specific revision.",
)
@config_option
@validate_config_option
@bind_key_option
@option("--sql", type=bool, help="Generate SQL output for offline migrations.", default=False, is_flag=True)
@option(
"--tag",
help="an arbitrary 'tag' that can be intercepted by custom env.py scripts via the .EnvironmentContext.get_tag_argument method.",
type=str,
default=None,
)
@no_prompt_option
@argument(
"revision",
type=str,
default="head",
)
def upgrade_database( # pyright: ignore[reportUnusedFunction]
bind_key: Optional[str], revision: str, sql: bool, tag: Optional[str], no_prompt: bool
) -> None:
"""Upgrade the database to the latest revision."""
from rich.prompt import Confirm
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
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:
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.upgrade(revision=revision, sql=sql, tag=tag)
@database_group.command(
help="Stamp the revision table with the given revision; don't run any migrations",
)
@config_option
@validate_config_option
@argument("revision", type=str)
@bind_key_option
@option("--sql", is_flag=True, default=False, help="Generate SQL output for offline migrations")
@option("--tag", type=str, default=None, help="Arbitrary 'tag' that can be intercepted by custom env.py scripts")
@option("--purge", is_flag=True, default=False, help="Delete all entries in version table before stamping")
def stamp(bind_key: Optional[str], revision: str, sql: bool, tag: Optional[str], purge: bool) -> None: # pyright: ignore[reportUnusedFunction]
"""Stamp the revision table with the given revision."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Stamping revision table[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.stamp(revision=revision, sql=sql, tag=tag, purge=purge)
@database_group.command(
name="check",
help="Check if the target database is up to date",
)
@config_option
@validate_config_option
@bind_key_option
def check_revision(bind_key: Optional[str]) -> None: # pyright: ignore[reportUnusedFunction]
"""Check for pending upgrade operations."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Checking for pending migrations[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.check()
@database_group.command(
name="edit",
help="Edit a revision file using $EDITOR",
)
@config_option
@validate_config_option
@argument("revision", type=str)
@bind_key_option
def edit_revision(bind_key: Optional[str], revision: str) -> None: # pyright: ignore[reportUnusedFunction]
"""Edit revision script with system editor."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule(f"[yellow]Opening revision {revision} in editor[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.edit(revision=revision)
@database_group.command(
name="ensure-version",
help="Create the alembic version table if it doesn't exist",
)
@config_option
@validate_config_option
@bind_key_option
@option("--sql", is_flag=True, default=False, help="Generate SQL output instead of executing")
def ensure_version_table(bind_key: Optional[str], sql: bool) -> None: # pyright: ignore[reportUnusedFunction]
"""Ensure alembic version table exists."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Ensuring version table exists[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.ensure_version(sql=sql)
@database_group.command(
name="heads",
help="Show current available heads in the script directory",
)
@config_option
@validate_config_option
@bind_key_option
@verbose_option
@option(
"--resolve-dependencies",
is_flag=True,
default=False,
help="Resolve dependencies between heads",
)
def show_heads(bind_key: Optional[str], verbose: bool, resolve_dependencies: bool) -> None: # pyright: ignore[reportUnusedFunction]
"""Show current heads."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Showing current heads[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.heads(verbose=verbose, resolve_dependencies=resolve_dependencies)
@database_group.command(
name="history",
help="List changeset scripts in chronological order",
)
@config_option
@validate_config_option
@bind_key_option
@verbose_option
@option(
"--rev-range",
type=str,
default=None,
help="Revision range (e.g., 'base:head', 'abc:def')",
)
@option(
"--indicate-current",
is_flag=True,
default=False,
help="Indicate the current revision",
)
def show_history( # pyright: ignore[reportUnusedFunction]
bind_key: Optional[str],
verbose: bool,
rev_range: Optional[str],
indicate_current: bool,
) -> None:
"""Show revision history."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Showing revision history[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.history(
rev_range=rev_range,
verbose=verbose,
indicate_current=indicate_current,
)
@database_group.command(
name="merge",
help="Merge two revisions together, creating a new migration file",
)
@config_option
@validate_config_option
@argument("revisions", type=str)
@bind_key_option
@option("-m", "--message", type=str, default=None, help="Merge message")
@option("--branch-label", type=str, default=None, help="Branch label for merge revision")
@option("--rev-id", type=str, default=None, help="Specify custom revision ID")
@no_prompt_option
def merge_revisions( # pyright: ignore[reportUnusedFunction]
bind_key: Optional[str],
revisions: str,
message: Optional[str],
branch_label: Optional[str],
rev_id: Optional[str],
no_prompt: bool,
) -> None:
"""Merge revisions (resolves multiple heads)."""
from rich.prompt import Prompt
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Merging revisions[/]", align="left")
if message is None:
message = "merge revisions" if no_prompt else Prompt.ask("Enter merge message")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.merge(
revisions=revisions,
message=message,
branch_label=branch_label,
rev_id=rev_id,
)
@database_group.command(
name="show",
help="Show the revision denoted by the given symbol",
)
@config_option
@validate_config_option
@argument("revision", type=str)
@bind_key_option
def show_revision(bind_key: Optional[str], revision: str) -> None: # pyright: ignore[reportUnusedFunction]
"""Show details of a specific revision."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule(f"[yellow]Showing revision {revision}[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.show(rev=revision)
@database_group.command(
name="branches",
help="Show current branch points in the migration history",
)
@config_option
@validate_config_option
@bind_key_option
@verbose_option
def show_branches(bind_key: Optional[str], verbose: bool) -> None: # pyright: ignore[reportUnusedFunction]
"""Show branch points."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Showing branch points[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.branches(verbose=verbose)
@database_group.command(
name="list-templates",
help="List available Alembic migration templates",
)
@config_option
@validate_config_option
@bind_key_option
def list_init_templates(bind_key: Optional[str]) -> None: # pyright: ignore[reportUnusedFunction]
"""List available initialization templates."""
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Available templates[/]", align="left")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.list_templates()
@database_group.command(
name="init",
help="Initialize migrations for the project.",
)
@config_option
@validate_config_option
@bind_key_option
@argument(
"directory",
default=None,
required=False,
)
@option("--multidb", is_flag=True, default=False, help="Support multiple databases")
@option("--package", is_flag=True, default=True, help="Create `__init__.py` for created folder")
@no_prompt_option
def init_alembic( # pyright: ignore[reportUnusedFunction]
bind_key: Optional[str], directory: Optional[str], multidb: bool, package: bool, no_prompt: bool
) -> None:
"""Initialize the database migrations."""
from rich.prompt import Confirm
from advanced_alchemy.alembic.commands import AlembicCommands
ctx = cast("click.Context", click.get_current_context())
configs = [get_config_by_bind_key(ctx, bind_key)] if bind_key is not None else _resolve_alchemy_configs(ctx)
console.rule("[yellow]Initializing database migrations.", align="left")
input_confirmed = (
True if no_prompt else Confirm.ask("[bold]Are you sure you want initialize migrations for the project?[/]")
)
if input_confirmed:
for config in configs:
target_directory = config.alembic_config.script_location if directory is None else directory
alembic_commands = AlembicCommands(sqlalchemy_config=config)
alembic_commands.init(directory=target_directory, multidb=multidb, package=package)
@database_group.command(
name="make-migrations",
help="Create a new migration revision.",
)
@config_option
@validate_config_option
@bind_key_option
@option("-m", "--message", default=None, help="Revision message")
@option(
"--autogenerate/--no-autogenerate", default=True, help="Automatically populate revision with detected changes"
)
@option("--sql", is_flag=True, default=False, help="Export to `.sql` instead of writing to the database.")
@option("--head", default="head", help="Specify head revision to use as base for new revision.")
@option("--splice", is_flag=True, default=False, help='Allow a non-head revision as the "head" to splice onto')
@option("--branch-label", default=None, help="Specify a branch label to apply to the new revision")
@option("--version-path", default=None, help="Specify specific path from config for version file")
@option("--rev-id", default=None, help="Specify a ID to use for revision.")
@no_prompt_option
def create_revision( # pyright: ignore[reportUnusedFunction]
bind_key: Optional[str],
message: Optional[str],
autogenerate: bool,
sql: bool,
head: str,
splice: bool,
branch_label: Optional[str],
version_path: Optional[str],
rev_id: Optional[str],
no_prompt: bool,
) -> None:
"""Create a new database revision."""
from rich.prompt import Prompt
from advanced_alchemy.alembic.commands import AlembicCommands
def process_revision_directives(
context: "MigrationContext", # noqa: ARG001
revision: tuple[str], # noqa: ARG001
directives: list["MigrationScript"],
) -> None:
"""Handle revision directives."""
if autogenerate and cast("UpgradeOps", directives[0].upgrade_ops).is_empty():
console.rule(
"[magenta]The generation of a migration file is being skipped because it would result in an empty file.",
style="magenta",
align="left",
)
console.rule(
"[magenta]More information can be found here. https://alembic.sqlalchemy.org/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect",
style="magenta",
align="left",
)
console.rule(
"[magenta]If you intend to create an empty migration file, use the --no-autogenerate option.",
style="magenta",
align="left",
)
directives.clear()
ctx = cast("click.Context", click.get_current_context())
sqlalchemy_config = get_config_by_bind_key(ctx, bind_key)
console.rule("[yellow]Starting database upgrade process[/]", align="left")
if message is None:
message = "autogenerated" if no_prompt else Prompt.ask("Please enter a message describing this revision")
alembic_commands = AlembicCommands(sqlalchemy_config=sqlalchemy_config)
alembic_commands.revision(
message=message,
autogenerate=autogenerate,
sql=sql,
head=head,
splice=splice,
branch_label=branch_label,
version_path=version_path,
rev_id=rev_id,
process_revision_directives=process_revision_directives, # type: ignore[arg-type]
)
@database_group.command(name="drop-all", help="Drop all tables from the database.")
@config_option
@validate_config_option
@bind_key_option
@no_prompt_option
def drop_all(bind_key: Optional[str], no_prompt: bool) -> None: # pyright: ignore[reportUnusedFunction]
"""Drop all tables from the database."""
from anyio import run
from rich.prompt import Confirm
from advanced_alchemy.alembic.utils import drop_all
from advanced_alchemy.base import metadata_registry
ctx = cast("click.Context", click.get_current_context())
configs = [get_config_by_bind_key(ctx, bind_key)] if bind_key is not None else _resolve_alchemy_configs(ctx)
console.rule("[yellow]Dropping all tables from the database[/]", align="left")
input_confirmed = no_prompt or Confirm.ask(
"[bold red]Are you sure you want to drop all tables from the database?"
)
async def _drop_all(
configs: "Sequence[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]]",
) -> None:
for config in configs:
engine = config.get_engine()
await drop_all(engine, config.alembic_config.version_table_name, metadata_registry.get(config.bind_key))
if input_confirmed:
run(_drop_all, configs)
@database_group.command(name="dump-data", help="Dump specified tables from the database to fixture files.")
@config_option
@validate_config_option
@bind_key_option
@option(
"--table",
"table_names",
help="Name of the table to dump. Multiple tables can be specified. Use '*' to dump all tables.",
type=str,
required=True,
multiple=True,
)
@option(
"--dir",
"dump_dir",
help="Directory to save the fixture files. Defaults to WORKDIR/fixtures",
type=click.Path(path_type=Path),
default=Path.cwd() / "fixtures",
required=False,
)
@option(
"--format",
"file_format",
type=click.Choice(["json", "jsonl", "csv"]),
default="json",
show_default=True,
help="Fixture file format.",
)
@option(
"--compression",
"compression",
type=click.Choice(["none", "gzip", "zip"]),
default="none",
show_default=True,
help="Compression applied to each fixture file.",
)
@option(
"--max-file-size",
"max_file_size",
type=BYTE_SIZE,
default=None,
help="Start a new numbered shard before a file would exceed this on-disk size, in bytes or with a K, M, or G suffix (1024-based), for example 50M.",
)
@option(
"--max-records",
"max_records",
type=click.IntRange(min=1),
default=None,
help="Start a new numbered shard after this many records.",
)
def dump_table_data( # pyright: ignore[reportUnusedFunction]
bind_key: Optional[str],
table_names: tuple[str, ...],
dump_dir: Path,
file_format: str,
compression: str,
max_file_size: Optional[int],
max_records: Optional[int],
) -> None:
"""Dump table data to fixture files."""
from anyio import run
from rich.prompt import Confirm
from advanced_alchemy.alembic.utils import dump_tables
from advanced_alchemy.base import metadata_registry, orm_registry
ctx = cast("click.Context", click.get_current_context())
configs = [get_config_by_bind_key(ctx, bind_key)] if bind_key is not None else _resolve_alchemy_configs(ctx)
all_tables = "*" in table_names
if all_tables and not Confirm.ask(
"[yellow bold]You have specified '*'. Are you sure you want to dump all tables from the database?",
):
return console.rule("[red bold]No data was dumped.", style="red", align="left")
async def _dump_tables() -> None:
for config in configs:
target_tables = set(metadata_registry.get(config.bind_key).tables)
if not all_tables:
for table_name in set(table_names) - target_tables:
console.rule(
f"[red bold]Skipping table '{table_name}' because it is not available in the default registry",
style="red",
align="left",
)
target_tables.intersection_update(table_names)
else:
console.rule("[yellow bold]Dumping all tables", style="yellow", align="left")
models = [
mapper.class_ for mapper in orm_registry.mappers if mapper.class_.__table__.name in target_tables
]
await dump_tables(
dump_dir,
config.get_session(),
models,
file_format=cast("FixtureFormat", file_format),
compression=None if compression == "none" else cast("FixtureCompression", compression),
max_bytes=max_file_size,
max_records=max_records,
)
console.rule("[green bold]Data dump complete", align="left")
return run(_dump_tables)
return database_group
class _ConsoleProxy:
"""Lazy Rich console proxy so registering CLI groups does not import ``rich``."""
__slots__ = ()
def rule(self, *args: Any, **kwargs: Any) -> None:
from rich import get_console
get_console().rule(*args, **kwargs)
def print(self, *args: Any, **kwargs: Any) -> None:
from rich import get_console
get_console().print(*args, **kwargs)
def _load_toml(pyproject_path: Path) -> dict[str, Any]:
"""Load TOML data from ``pyproject_path`` using ``tomllib`` or ``tomli``."""
toml_mod = import_module("tomllib" if sys.version_info >= (3, 11) else "tomli")
with pyproject_path.open("rb") as f:
return cast("dict[str, Any]", toml_mod.load(f))
def _normalize_config_path(config_path: str) -> str:
"""Normalize supported config path syntax to a dotted path.
Args:
config_path: Dotted ``module.attribute`` or ``module:attribute`` path.
Returns:
A dotted path string.
Raises:
ImproperConfigurationError: If ``:`` is used with invalid syntax.
"""
from advanced_alchemy.exceptions import ImproperConfigurationError
module_path, separator, attribute_path = config_path.partition(":")
if not separator:
return config_path
if not module_path or not attribute_path or ":" in attribute_path:
msg = (
f"Config path '{config_path}' is not a valid reference. "
"Use 'module:attribute' with a single ':', or dotted 'module.attribute'."
)
raise ImproperConfigurationError(msg)
return f"{module_path}.{attribute_path}"
def _import_config_target(config_path: str) -> Any:
"""Import a config target or module from ``config_path``."""
from advanced_alchemy.utils import module_loader
normalized = _normalize_config_path(config_path)
if "." not in normalized:
return import_module(normalized)
try:
return module_loader.import_string(normalized)
except ImportError as orig_err:
try:
return import_module(normalized)
except ImportError:
raise orig_err from None
def _run_coroutine_sync(coro: "Coroutine[Any, Any, Any]") -> Any:
"""Execute a coroutine from synchronous code even when an event loop is running."""
try:
asyncio.get_running_loop()
except RuntimeError:
return asyncio.run(coro)
with ThreadPoolExecutor(max_workers=1) as executor:
return executor.submit(asyncio.run, coro).result()
def _is_direct_config(config: Any) -> bool:
"""Return ``True`` if ``config`` is a direct SQLAlchemy config instance."""
if isinstance(config, type):
return False
return (
getattr(config, "alembic_config", None) is not None
and hasattr(config, "bind_key")
and callable(getattr(config, "get_engine", None))
)
def _is_sequence_not_str(value: Any) -> bool:
"""Return ``True`` when ``value`` is a non-string, non-bytes ``Sequence``."""
return isinstance(value, Sequence) and not isinstance(value, (str, bytes))
def _is_valid_config(config: Any) -> bool:
"""Return ``True`` if ``config`` is a direct config or a wrapper exposing ``.config``."""
if _is_direct_config(config):
return True
if isinstance(config, type) or not hasattr(config, "config"):
return False
nested: Any = getattr(config, "config", None)
if _is_direct_config(nested):
return True
if not _is_sequence_not_str(nested):
return False
nested_items = cast("Sequence[Any]", nested)
return bool(nested_items) and all(_is_direct_config(item) for item in nested_items)
def _unwrap_nested_configs(config: Any) -> "list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]]":
"""Unwrap a config or wrapper object into a flat list of direct configs."""
if _is_direct_config(config):
return [cast("Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]", config)]
nested: Any = getattr(config, "config", config)
if _is_sequence_not_str(nested):
nested_items = cast("Sequence[Any]", nested)
return [cast("Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]", item) for item in nested_items]
return [cast("Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]", nested)]
def _is_valid_config_or_sequence(value: Any) -> bool:
"""Return ``True`` if ``value`` is a valid config or non-empty sequence of valid configs."""
if _is_valid_config(value):
return True
if not _is_sequence_not_str(value):
return False
items = cast("Sequence[Any]", value)
return bool(items) and all(_is_valid_config(item) for item in items)
def _describe_module_reference(module: ModuleType, config_path: str) -> str:
"""Build an actionable error message when ``config_path`` resolves to a module."""
candidates = sorted(
name for name, value in vars(module).items() if not name.startswith("_") and _is_valid_config_or_sequence(value)
)
if candidates:
examples = ", ".join(f"'{config_path}:{name}'" for name in candidates)
return (
f"Config '{config_path}' names a module, not a database configuration. "
f"Point at the configuration itself, for example {examples}."
)
return (
f"Config '{config_path}' names a module that exports no database configuration. "
"Point at a config instance, a list of configs, or a factory returning them, "
"using 'module:attribute' or 'module.attribute'."
)
def _validate_config_result(
config_result: Any, config_path: str
) -> "Union[list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]], SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]":
"""Validate and unwrap a resolved configuration result."""
from advanced_alchemy.exceptions import ImproperConfigurationError
if isinstance(config_result, ModuleType):
raise ImproperConfigurationError(_describe_module_reference(config_result, config_path))
if config_result is None:
msg = f"Config '{config_path}' resolved to None. Expected config instance or list of configs."
raise ImproperConfigurationError(msg)
if _is_sequence_not_str(config_result):
result_items = cast("Sequence[Any]", config_result)
if not result_items:
msg = f"Config '{config_path}' resolved to empty list. Expected at least one config."
raise ImproperConfigurationError(msg)
unwrapped_list: list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]] = []
for i, item in enumerate(result_items):
if not _is_valid_config(item):
msg = (
f"Config '{config_path}' returned invalid config at index {i}. "
"Expected SQLAlchemyAsyncConfig or SQLAlchemySyncConfig instance."
)
raise ImproperConfigurationError(msg)
unwrapped_list.extend(_unwrap_nested_configs(item))
return unwrapped_list
if not _is_valid_config(config_result):
msg = (
f"Config '{config_path}' returned invalid type '{type(config_result).__name__}'. "
"Expected SQLAlchemyAsyncConfig or SQLAlchemySyncConfig instance or list."
)
raise ImproperConfigurationError(msg)
unwrapped = _unwrap_nested_configs(config_result)
if len(unwrapped) == 1:
return unwrapped[0]
return unwrapped
def _emit_validation_summary(
console: Any,
configs: "Sequence[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]]",
) -> None:
"""Print configuration validation output to the console."""
from advanced_alchemy.config import SQLAlchemyAsyncConfig
console.print(f"[green]✓[/] Successfully loaded {len(configs)} config(s)")
for i, cfg in enumerate(configs):
config_name = cfg.bind_key or f"config-{i}"
config_type = type(cfg).__name__
is_async = isinstance(cfg, SQLAlchemyAsyncConfig) or bool(getattr(cfg, "is_async", False))
execution_hint = "[dim cyan](async-capable)[/]" if is_async else "[dim](sync)[/]"
console.print(f" [dim]•[/] {config_name}: {config_type} {execution_hint}")
def _print_missing_config_error(console: Any) -> None:
"""Print actionable instructions when no CLI configuration can be found."""
from rich.markup import escape
console.print("[red]Error: No Advanced Alchemy config found.[/]")
console.print("\nSpecify config using one of:")
console.print(" 1. CLI flag: alchemy --config myapp.config:alchemy_config <command>")
console.print(" 2. Environment var: export ALCHEMY_CONFIG=myapp.config:alchemy_config")
console.print(f" 3. pyproject.toml: {escape('[tool.advanced-alchemy]')}")
console.print(' config = "myapp.config:alchemy_config"')
def _load_and_deduplicate_configs(
effective_path: str,
) -> "list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]]":
"""Resolve comma-separated config paths and deduplicate by ``bind_key`` (later wins)."""
all_configs: list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]] = []
for raw_segment in effective_path.split(","):
segment = raw_segment.strip()
if not segment:
continue
resolved = resolve_config_sync(segment)
if isinstance(resolved, list):
all_configs.extend(resolved)
else:
all_configs.append(resolved)
configs_list: list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]] = []
seen_bind_keys: dict[str, int] = {}
for cfg in all_configs:
if cfg.bind_key is not None and cfg.bind_key in seen_bind_keys:
configs_list[seen_bind_keys[cfg.bind_key]] = cfg
else:
if cfg.bind_key is not None:
seen_bind_keys[cfg.bind_key] = len(configs_list)
configs_list.append(cfg)
return configs_list
def _maybe_validate_configs(
ctx: "Any",
console: Any,
configs: "Sequence[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]]",
) -> None:
"""Emit validation summary once when ``--validate-config`` is active."""
if ctx.obj.get("validate_config") and not ctx.obj.get("_config_validated"):
ctx.obj["_config_validated"] = True
_emit_validation_summary(console, configs)
def _resolve_alchemy_configs(
ctx: "Any",
config_path: Optional[str] = None,
) -> "Sequence[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]]":
"""Load or retrieve SQLAlchemy configs from CLI option, env var, ``pyproject.toml``, or ``ctx.obj``."""
from rich import get_console
from rich.markup import escape
from advanced_alchemy.exceptions import AdvancedAlchemyError
ctx.ensure_object(dict)
console = get_console()
effective_path: Optional[str] = (
config_path if config_path is not None else cast("Optional[str]", ctx.obj.get("config_path"))
)
if effective_path is None and ctx.obj.get("configs"):
existing_configs = cast(
"Sequence[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]]",
ctx.obj["configs"],
)
_maybe_validate_configs(ctx, console, existing_configs)
return existing_configs
if effective_path is None:
effective_path = discover_config_from_pyproject()
if effective_path is not None:
console.print("[dim]Using config from pyproject.toml[/]")
if effective_path is None:
_print_missing_config_error(console)
ctx.exit(1)
raise SystemExit(1)
cwd = str(Path.cwd())
added_cwd = cwd not in sys.path
if added_cwd:
sys.path.insert(0, cwd)
try:
configs_list = _load_and_deduplicate_configs(effective_path)
except (ImportError, AdvancedAlchemyError) as e:
console.print(f"[red]Error loading config: {escape(str(e))}[/]", emoji=False)
ctx.exit(1)
raise
else:
if not configs_list:
console.print("[red]Error: No valid configs found after resolution.[/]")
console.print("\nEnsure your config path returns valid config instance(s).")
ctx.exit(1)
raise SystemExit(1)
ctx.obj["configs"] = configs_list
ctx.obj["config_path"] = None
_maybe_validate_configs(ctx, console, configs_list)
return configs_list
finally:
if added_cwd and cwd in sys.path and sys.path[0] == cwd:
sys.path.remove(cwd)
def _config_option(click_mod: Any) -> Callable[[Any], Any]:
"""Build a reusable ``--config`` / ``-c`` Click option decorator."""
from click.core import ParameterSource
def _callback(ctx: "Any", param: "Any", value: Optional[str]) -> Optional[str]:
if value is None or not value.strip():
return None
ctx.ensure_object(dict)
source = ctx.get_parameter_source(param.name) if hasattr(ctx, "get_parameter_source") else None
current_source = ctx.obj.get("config_source")
if source == ParameterSource.ENVIRONMENT and current_source == ParameterSource.COMMANDLINE:
return value
ctx.obj["config_path"] = value
ctx.obj["config_source"] = source
return value
return cast(
"Callable[[Any], Any]",
click_mod.option(
"--config",
"-c",
help="Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)",
required=False,
default=None,
type=str,
envvar="ALCHEMY_CONFIG",
expose_value=False,
callback=_callback,
),
)
def _validate_config_option(click_mod: Any) -> Callable[[Any], Any]:
"""Build a reusable ``--validate-config`` Click option decorator."""
def _callback(ctx: "Any", _param: "Any", value: bool) -> bool:
if value:
ctx.ensure_object(dict)
ctx.obj["validate_config"] = True
return value
return cast(
"Callable[[Any], Any]",
click_mod.option(
"--validate-config",
is_flag=True,
default=False,
help="Validate configuration before executing migrations",
expose_value=False,
callback=_callback,
),
)