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

alembic.command.current(config, verbose=False, head_only=False)

Display the current revision for a database.

alembic.command.downgrade(config, revision, sql=False, tag=None)

Revert to a previous version.

alembic.command.edit(config, rev)

Edit revision script(s) using $EDITOR

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

Show current available heads in the script directory

alembic.command.history(config, rev_range=None, verbose=False)

List changeset scripts in chronological order.

alembic.command.init(config, directory, template='generic')

Initialize a new scripts directory.

alembic.command.list_templates(config)

List available templates

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.

See also

branches

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)

Create a new revision file.

alembic.command.show(config, rev)

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

alembic.command.stamp(config, revision, sql=False, tag=None)

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

alembic.command.upgrade(config, revision, sql=False, tag=None)

Upgrade to a later version.