Skip to main content
`Ctrl`+`K`

# 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: Config, verbose: bool = False) → None

  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.

  Added in version 1.9.0.

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

  Display the current revision for a database.

  Parameters:

    - config – a `Config` instance.

    - check_heads –

      Check if all head revisions are applied to the database. Raises `DatabaseNotAtHead` if this is not the case.

      Added in version 1.17.1.

    - 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. May be `"base"` to target the first revision.

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

      Added in version 1.7.6.

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

  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) → None

  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

    - revisions – The revisions to merge.

    - 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 | os.PathLike[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: Config, rev: str) → None

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

  Parameters:

    - config – a `Config` instance.

    - rev – string revision target. May be `"current"` to show the revision(s) currently applied in the database.

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; may be `"base"` to remove all revisions from the table or `"heads"` to stamp the most recent revision(s).

      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. May be `"heads"` to target the most recent revision(s).

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