Commands

Note

this section discusses the internal API of Alembic as regards its command invocation system. This section is only useful for developers who wish to extend the capabilities of Alembic. For documentation on using Alembic commands, please see Tutorial.

Alembic commands are all represented by functions in the Commands package. They all accept the same style of usage, being sent the Config object as the first argument.

Commands can be run programmatically, by first constructing a Config object, as in:

from alembic.config import Config
from alembic import command
alembic_cfg = Config("/path/to/yourapp/alembic.ini")
command.upgrade(alembic_cfg, "head")

In many cases, and perhaps more often than not, an application will wish to call upon a series of Alembic commands and/or other features. It is usually a good idea to link multiple commands along a single connection and transaction, if feasible. This can be achieved using the Config.attributes dictionary in order to share a connection:

with engine.begin() as connection:
    alembic_cfg.attributes['connection'] = connection
    command.upgrade(alembic_cfg, "head")

This recipe requires that env.py consumes this connection argument; see the example in Sharing a Connection across one or more programmatic migration commands for details.

To write small API functions that make direct use of database and script directory information, rather than just running one of the built-in commands, use the ScriptDirectory and MigrationContext classes directly.

alembic.command.branches(config, verbose=False)

Show current branch points.

Parameters:

  • config – a Config instance.

  • verbose – output in verbose mode.

alembic.command.check(config: Config) → None

Check if revision command with autogenerate has pending upgrade ops.

Parameters:

config – a Config object.

New in version 1.9.0.

alembic.command.current(config: Config, verbose: bool = False) → None

Display the current revision for a database.

Parameters:

  • config – a Config instance.

  • verbose – output in verbose mode.

alembic.command.downgrade(config: Config, revision: str, sql: bool = False, tag: str | None = None) → None

Revert to a previous version.

Parameters:

  • config – a Config instance.

  • revision – string revision target or range for –sql mode

  • sql – if True, use --sql mode

  • tag – an arbitrary “tag” that can be intercepted by custom env.py scripts via the EnvironmentContext.get_tag_argument() method.

alembic.command.edit(config: Config, rev: str) → None

Edit revision script(s) using $EDITOR.

Parameters:

  • config – a Config instance.

  • rev – target revision.

alembic.command.ensure_version(config: Config, sql: bool = False) → None

Create the alembic version table if it doesn’t exist already .

Parameters:

  • config – a Config instance.

  • sql –

    use --sql mode

    New in version 1.7.6.

alembic.command.heads(config, verbose=False, resolve_dependencies=False)

Show current available heads in the script directory.

Parameters:

  • config – a Config instance.

  • verbose – output in verbose mode.

  • resolve_dependencies – treat dependency version as down revisions.

alembic.command.history(config: Config, rev_range: str | None = None, verbose: bool = False, indicate_current: bool = False) → None

List changeset scripts in chronological order.

Parameters:

  • config – a Config instance.

  • rev_range – string revision range

  • verbose – output in verbose mode.

  • indicate_current – indicate current revision.

alembic.command.init(config: Config, directory: str, template: str = 'generic', package: bool = False) → None

Initialize a new scripts directory.

Parameters:

  • config – a Config object.

  • directory – string path of the target directory

  • template – string name of the migration environment template to use.

  • package – when True, write __init__.py files into the environment location as well as the versions/ location.

alembic.command.list_templates(config: Config)

List available templates.

Parameters:

config – a Config object.

alembic.command.merge(config: Config, revisions: _RevIdType, message: str | None = None, branch_label: _RevIdType | None = None, rev_id: str | None = None) → Script | None

Merge two revisions together. Creates a new migration file.

Parameters:

  • config – a Config instance

  • message – string message to apply to the revision

  • branch_label – string label name to apply to the new revision

  • rev_id – hardcoded revision identifier instead of generating a new one.

See also

Working with Branches

alembic.command.revision(config: Config, message: str | None = None, autogenerate: bool = False, sql: bool = False, head: str = 'head', splice: bool = False, branch_label: _RevIdType | None = None, version_path: str | None = None, rev_id: str | None = None, depends_on: str | None = None, process_revision_directives: ProcessRevisionDirectiveFn | None = None) → Script | None | List[Script | None]

Create a new revision file.

Parameters:

  • config – a Config object.

  • message – string message to apply to the revision; this is the -m option to alembic revision.

  • autogenerate – whether or not to autogenerate the script from the database; this is the --autogenerate option to alembic revision.

  • sql – whether to dump the script out as a SQL string; when specified, the script is dumped to stdout. This is the --sql option to alembic revision.

  • head – head revision to build the new revision upon as a parent; this is the --head option to alembic revision.

  • splice – whether or not the new revision should be made into a new head of its own; is required when the given head is not itself a head. This is the --splice option to alembic revision.

  • branch_label – string label to apply to the branch; this is the --branch-label option to alembic revision.

  • version_path – string symbol identifying a specific version path from the configuration; this is the --version-path option to alembic revision.

  • rev_id – optional revision identifier to use instead of having one generated; this is the --rev-id option to alembic revision.

  • depends_on – optional list of “depends on” identifiers; this is the --depends-on option to alembic revision.

  • process_revision_directives – this is a callable that takes the same form as the callable described at EnvironmentContext.configure.process_revision_directives; will be applied to the structure generated by the revision process where it can be altered programmatically. Note that unlike all the other parameters, this option is only available via programmatic use of command.revision()

alembic.command.show(config, rev)

Show the revision(s) denoted by the given symbol.

Parameters:

  • config – a Config instance.

  • revision – string revision target

alembic.command.stamp(config: Config, revision: _RevIdType, sql: bool = False, tag: str | None = None, purge: bool = False) → None

‘stamp’ the revision table with the given revision; don’t run any migrations.

Parameters:

  • config – a Config instance.

  • revision –

    target revision or list of revisions. May be a list to indicate stamping of multiple branch heads.

    Note

    this parameter is called “revisions” in the command line interface.

  • sql – use --sql mode

  • tag – an arbitrary “tag” that can be intercepted by custom env.py scripts via the EnvironmentContext.get_tag_argument method.

  • purge – delete all entries in the version table before stamping.

alembic.command.upgrade(config: Config, revision: str, sql: bool = False, tag: str | None = None) → None

Upgrade to a later version.

Parameters:

  • config – a Config instance.

  • revision – string revision target or range for –sql mode

  • sql – if True, use --sql mode

  • tag – an arbitrary “tag” that can be intercepted by custom env.py scripts via the EnvironmentContext.get_tag_argument() method.