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
clickpackage is not installed.- Returns:
The Advanced Alchemy CLI group.
- Return type:
Group
- advanced_alchemy.cli.discover_config_from_pyproject()[source]#
Find and parse
pyproject.tomlfor Advanced Alchemy CLI configuration.Walks upward from the current working directory to locate
pyproject.tomland parses[tool.advanced-alchemy](or[tool.advanced_alchemy]/[tool.alchemy]) for theconfigkey.- Returns:
Configured path string (comma-separated when configured as a list), or
Nonewhen not found.- Return type:
str | None
- advanced_alchemy.cli.find_pyproject_toml()[source]#
Walk the filesystem upward from
Path.cwd()to findpyproject.toml.Stops at a
.gitdirectory boundary (repository root) or the filesystem root.- Returns:
Path to
pyproject.toml, orNoneif not found.- Return type:
Path | None
- advanced_alchemy.cli.parse_pyproject_config(pyproject_path)[source]#
Parse
pyproject.tomlfor Advanced Alchemy CLI configuration.Checks
[tool.advanced-alchemy],[tool.advanced_alchemy], and[tool.alchemy]in order for aconfigentry.- Parameters:
pyproject_path (Path) – Path to the
pyproject.tomlfile.- Returns:
Config path(s) as a string (converting a list of strings to a comma-separated string), or
Noneif no config is defined.- Raises:
ValueError – If the
pyproject.tomlfile cannot be parsed or theconfigvalue 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 asSQLAlchemyInitPluginorAdvancedAlchemy), synchronous factory callables, and asynchronous coroutine factories.- Parameters:
config_path (str) –
module.attributeormodule:attributepath 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 asSQLAlchemyInitPluginorAdvancedAlchemy), synchronous factory callables, and asynchronous coroutine factories.- Parameters:
config_path (str) –
module.attributeormodule:attributepath 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]