Commands — Alembic 1.4.1 documentation

# 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, indicate_current=False)

  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.

      ..versionadded:: 0.9.9

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

  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.

      New in version 1.2.

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

  See also

  Working with 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, 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, purge=False)

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

      Changed in version 1.2: The revision may be a single revision or list of revisions when stamping multiple branch heads.

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

      New in version 1.2.

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