# 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.