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
Config object as the first argument.
Commands can be run programmatically, by first constructing a
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,
- alembic.command.branches(config, verbose=False)¶
Show current branch points.
- alembic.command.check(config: Config) None ¶
Check if revision command with autogenerate has pending upgrade ops.
New in version 1.9.0.
- alembic.command.current(config: Config, verbose: bool = False) None ¶
Display the current revision for a database.
- alembic.command.downgrade(config: Config, revision: str, sql: bool = False, tag: str | None = None) None ¶
Revert to a previous version.
- alembic.command.edit(config: Config, rev: str) None ¶
Edit revision script(s) using $EDITOR.
- alembic.command.ensure_version(config: Config, sql: bool = False) None ¶
Create the alembic version table if it doesn’t exist already .
- alembic.command.heads(config, verbose=False, resolve_dependencies=False)¶
Show current available heads in the script directory.
- alembic.command.history(config: Config, rev_range: str | None = None, verbose: bool = False, indicate_current: bool = False) None ¶
List changeset scripts in chronological order.
- alembic.command.init(config: Config, directory: str, template: str = 'generic', package: bool = False) None ¶
Initialize a new scripts directory.
- alembic.command.list_templates(config: Config)¶
List available templates.
- alembic.command.merge(config: Config, revisions: str, message: str | None = None, branch_label: str | None = None, rev_id: str | None = None) Script | None ¶
Merge two revisions together. Creates a new migration file.
- alembic.command.revision(config: Config, message: str | None = None, autogenerate: bool = False, sql: bool = False, head: str = 'head', splice: bool = False, branch_label: str | None = None, version_path: 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.
message¶ – string message to apply to the revision; this is the
autogenerate¶ – whether or not to autogenerate the script from the database; this is the
sql¶ – whether to dump the script out as a SQL string; when specified, the script is dumped to stdout. This is the
head¶ – head revision to build the new revision upon as a parent; this is the
splice¶ – whether or not the new revision should be made into a new head of its own; is required when the given
headis not itself a head. This is the
branch_label¶ – string label to apply to the branch; this is the
version_path¶ – string symbol identifying a specific version path from the configuration; this is the
rev_id¶ – optional revision identifier to use instead of having one generated; this is the
depends_on¶ – optional list of “depends on” identifiers; this is the
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
- alembic.command.show(config, rev)¶
Show the revision(s) denoted by the given symbol.
- alembic.command.stamp(config: Config, revision: str, sql: bool = False, tag: str | None = None, purge: bool = False) None ¶
‘stamp’ the revision table with the given revision; don’t run any migrations.
target revision or list of revisions. May be a list to indicate stamping of multiple branch heads.
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
tag¶ – an arbitrary “tag” that can be intercepted by custom
env.pyscripts via the
delete all entries in the version table before stamping.
New in version 1.2.
- alembic.command.upgrade(config: Config, revision: str, sql: bool = False, tag: str | None = None) None ¶
Upgrade to a later version.