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 with a Series of Migration Commands and Environments 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.current(config, verbose=False, head_only=False)

Display the current revision for a database.

Parameters:
  • config – a Config instance.
  • verbose – output in verbose mode.
  • head_only – deprecated; use verbose for additional output.
alembic.command.downgrade(config, revision, sql=False, tag=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, rev)

Edit revision script(s) using $EDITOR.

Parameters:
  • config – a Config instance.
  • rev – target revision.
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, rev_range=None, verbose=False)

List changeset scripts in chronological order.

Parameters:
  • config – a Config instance.
  • rev_range – string revision range
  • verbose – output in verbose mode.
alembic.command.init(config, directory, template='generic')

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.
alembic.command.list_templates(config)

List available templates

Parameters:config – a Config object.
alembic.command.merge(config, revisions, message=None, branch_label=None, rev_id=None)

Merge two revisions together. Creates a new migration file.

New in version 0.7.0.

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.
alembic.command.revision(config, message=None, autogenerate=False, sql=False, head='head', splice=False, branch_label=None, version_path=None, rev_id=None, depends_on=None, process_revision_directives=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()

    New in version 0.9.0.

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, revision, sql=False, tag=None)

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

Parameters:
  • config – a Config instance.
  • revision – target revision.
  • sql – 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.upgrade(config, revision, sql=False, tag=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.