Command-Line Interface#

Command-line interface and migration commands for Advanced Alchemy.

CLI Commands#

alchemy#

Advanced Alchemy CLI commands.

Usage

alchemy [OPTIONS] COMMAND [ARGS]...

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

branches#

Show current branch points in the migration history

Usage

alchemy branches [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--verbose#

Enable verbose output.

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

check#

Check if the target database is up to date

Usage

alchemy check [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

downgrade#

Downgrade database to a specific revision.

Usage

alchemy downgrade [OPTIONS] [REVISION]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--sql#

Generate SQL output for offline migrations.

--tag <tag>#

an arbitrary ‘tag’ that can be intercepted by custom env.py scripts via the .EnvironmentContext.get_tag_argument method.

--no-prompt#

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

REVISION#

Optional argument

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

drop-all#

Drop all tables from the database.

Usage

alchemy drop-all [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--no-prompt#

Do not prompt for confirmation before executing the command.

Default:

False

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

dump-data#

Dump specified tables from the database to fixture files.

Usage

alchemy dump-data [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--table <table_names>#

Required Name of the table to dump. Multiple tables can be specified. Use ‘*’ to dump all tables.

--dir <dump_dir>#

Directory to save the fixture files. Defaults to WORKDIR/fixtures

--format <file_format>#

Fixture file format.

Default:

'json'

Options:

json | jsonl | csv

--compression <compression>#

Compression applied to each fixture file.

Default:

'none'

Options:

none | gzip | zip

--max-file-size <max_file_size>#

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.

--max-records <max_records>#

Start a new numbered shard after this many records.

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

edit#

Edit a revision file using $EDITOR

Usage

alchemy edit [OPTIONS] REVISION

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

Arguments

REVISION#

Required argument

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

ensure-version#

Create the alembic version table if it doesn’t exist

Usage

alchemy ensure-version [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--sql#

Generate SQL output instead of executing

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

heads#

Show current available heads in the script directory

Usage

alchemy heads [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--verbose#

Enable verbose output.

--resolve-dependencies#

Resolve dependencies between heads

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

history#

List changeset scripts in chronological order

Usage

alchemy history [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--verbose#

Enable verbose output.

--rev-range <rev_range>#

Revision range (e.g., ‘base:head’, ‘abc:def’)

--indicate-current#

Indicate the current revision

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

init#

Initialize migrations for the project.

Usage

alchemy init [OPTIONS] [DIRECTORY]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--multidb#

Support multiple databases

--package#

Create __init__.py for created folder

--no-prompt#

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

DIRECTORY#

Optional argument

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

list-templates#

List available Alembic migration templates

Usage

alchemy list-templates [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

make-migrations#

Create a new migration revision.

Usage

alchemy make-migrations [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

-m, --message <message>#

Revision message

--autogenerate, --no-autogenerate#

Automatically populate revision with detected changes

--sql#

Export to .sql instead of writing to the database.

--head <head>#

Specify head revision to use as base for new revision.

--splice#

Allow a non-head revision as the “head” to splice onto

--branch-label <branch_label>#

Specify a branch label to apply to the new revision

--version-path <version_path>#

Specify specific path from config for version file

--rev-id <rev_id>#

Specify a ID to use for revision.

--no-prompt#

Do not prompt for confirmation before executing the command.

Default:

False

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

merge#

Merge two revisions together, creating a new migration file

Usage

alchemy merge [OPTIONS] REVISIONS

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

-m, --message <message>#

Merge message

--branch-label <branch_label>#

Branch label for merge revision

--rev-id <rev_id>#

Specify custom revision ID

--no-prompt#

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

REVISIONS#

Required argument

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

show#

Show the revision denoted by the given symbol

Usage

alchemy show [OPTIONS] REVISION

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

Arguments

REVISION#

Required argument

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

show-config#

Show all configurations with migrations enabled.

Usage

alchemy show-config [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

show-current-revision#

Shows the current revision for the database.

Usage

alchemy show-current-revision [OPTIONS]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--verbose#

Enable verbose output.

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

stamp#

Stamp the revision table with the given revision; don’t run any migrations

Usage

alchemy stamp [OPTIONS] REVISION

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--sql#

Generate SQL output for offline migrations

--tag <tag>#

Arbitrary ‘tag’ that can be intercepted by custom env.py scripts

--purge#

Delete all entries in version table before stamping

Arguments

REVISION#

Required argument

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

upgrade#

Upgrade database to a specific revision.

Usage

alchemy upgrade [OPTIONS] [REVISION]

Options

-c, --config <config>#

Dotted or colon path to SQLAlchemy config(s) or factory callable (env: ALCHEMY_CONFIG)

--validate-config#

Validate configuration before executing migrations

--bind-key <bind_key>#

Specify which SQLAlchemy config to use by bind key

--sql#

Generate SQL output for offline migrations.

--tag <tag>#

an arbitrary ‘tag’ that can be intercepted by custom env.py scripts via the .EnvironmentContext.get_tag_argument method.

--no-prompt#

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

REVISION#

Optional argument

Environment variables

ALCHEMY_CONFIG

Provide a default for --config

Configuration & Discovery Helpers#

advanced_alchemy.cli.add_migration_commands(database_group=None)[source]#

Add migration commands to the database group.

Parameters:

database_group (Group | None) – The database group to add the commands to.

Returns:

The database group with the migration commands added.

Return type:

Group

advanced_alchemy.cli.get_alchemy_group()[source]#

Get the Advanced Alchemy CLI group.

Raises:

MissingDependencyError – If the click package is not installed.

Returns:

The Advanced Alchemy CLI group.

Return type:

Group

advanced_alchemy.cli.discover_config_from_pyproject()[source]#

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.

Return type:

str | None

advanced_alchemy.cli.find_pyproject_toml()[source]#

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.

Return type:

Path | None

advanced_alchemy.cli.parse_pyproject_config(pyproject_path)[source]#

Parse pyproject.toml for Advanced Alchemy CLI configuration.

Checks [tool.advanced-alchemy], [tool.advanced_alchemy], and [tool.alchemy] in order for a config entry.

Parameters:

pyproject_path (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.

Return type:

str | None

async advanced_alchemy.cli.resolve_config_async(config_path)[source]#

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.

Parameters:

config_path (str) – 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.

Return type:

Union[list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]], SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]

advanced_alchemy.cli.resolve_config_sync(config_path)[source]#

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.

Parameters:

config_path (str) – 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.

Return type:

Union[list[Union[SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]], SQLAlchemyAsyncConfig, SQLAlchemySyncConfig]