API

Anything documented here is part of the public API that Flask-Alembic provides, unless otherwise indicated. Anything not documented here is considered internal or private and may change at any time.

class flask_alembic.Alembic(app=None, *, run_mkdir=True, command_name='db', metadatas=None, engines=None)

Provide an Alembic environment and migration API.

If instantiated without an app instance, init_app() is used to register an app at a later time.

Configures basic logging to stderr for the sqlalchemy and alembic loggers if they do not already have handlers.

Parameters:

• app (Flask | None) – Call init_app on this app.

• run_mkdir (bool) – Run mkdir() during init_app.

• command_name (str) – Register a Click command with this name during init_app, unless it is the empty string.

• metadatas (sa.MetaData | list[sa.MetaData] | dict[str, sa.MetaData | list[sa.MetaData]] | None) – One or more MetaData to inspect when generating migrations. A single metadata or list will be assigned to the "default" key. Or a map can be given that specifies one or more metadata for each key. When using Flask-SQLAlchemy, db.metadata is used if this is not given.

• engines (sa.Engine | dict[str, sa.Engine] | None) – One or more engines to perform migrations on. Must match the keys in metadatas. A single engine will be assigned to the "default" key. Or a map can be given that specifies the engine for each key. When using Flask-SQLAlchemy(-Lite), db.engines is used if this is not given.

Changelog

Changed in version 3.1: Added the metadatas and enginess arguments. Support Flask-SQLAlchemy-Lite and plain SQLAlchemy in addition to Flask-SQLAlchemy. Support multiple databases and multiple metadata per database.

Changed in version 3.1: run_mkdir and command_name are keyword-only arguments.

init_app(app)

Register this extension on an app.

Parameters:

app (Flask) – App to register.

Return type:

None

Changed in version 3.2: run_mkdir and command_name args are removed.

rev_id()

Generate a unique id for a revision.

By default, this uses the current UTC timestamp. Override this method, or assign a static method, to change this.

Changelog

Changed in version 3.0: Uses the current UTC timestamp instead of a UUID.

Return type:

str

property config: Config

Get the Alembic Config for the current app.

property script_directory: ScriptDirectory

Get the Alembic ScriptDirectory for the current app.

property environment_context: EnvironmentContext

Get the Alembic EnvironmentContext for the current app.

property migration_contexts: dict[str, MigrationContext]

Get the map of Alembic MigrationContext for each configured database key for the current app. Each context’s connection will be closed when the Flask application context ends.

Changelog

Added in version 3.1.

property migration_context: MigrationContext

Get the Alembic MigrationContext for the current app. If multiple databases are configured, this is the context for the "default" key. The context’s connection will be closed when the Flask application context ends.

property ops: dict[str, Operations]

Get the Alembic Operations context for each configured database key for the current app.

Changelog

Added in version 3.1.

property op: Operations

Get the Alembic Operations context for the current app. If multiple databases are configured, this is the context for the "default" key.

run_migrations(fn, **kwargs)

Configure an Alembic MigrationContext to run migrations for the given function.

This takes the place of Alembic’s env.py file, specifically the run_migrations_online function.

Parameters:

• fn (Callable[[str | list[str] | tuple[str, ...], MigrationContext], list[MigrationStep]]) – Use this function to control what migrations are run.

• kwargs (Any) – Extra arguments passed to upgrade or downgrade in each revision.

Return type:

None

Changelog

Changed in version 3.1: Support multiple databases.

mkdir()

Create the script directory and template.

Alembic’s generic template is used if a single database is configured. The multidb template if multiple databases are configured.

Changelog

Changed in version 3.1: Support multiple databases.

Return type:

None

current()

Get the list of current revisions.

Return type:

tuple[Script, …]

needs_upgrade()

Check whether the current revisions are the head revisions.

Returns:

True if the database is not at all head revisions, False otherwise.

Return type:

bool

heads(resolve_dependencies=False)

Get the list of revisions that have no child revisions.

Parameters:

resolve_dependencies (bool) – Treat dependencies as down revisions.

Return type:

tuple[Script, …]

branches()

Get the list of revisions that have more than one next revision.

Return type:

list[Script]

log(start='base', end='heads')

Get the list of revisions in the order they will run.

Parameters:

• start (str | Script | list[str] | list[Script] | tuple[str, ...] | tuple[Script, ...]) – Only get entries since this revision.

• end (str | Script | list[str] | list[Script] | tuple[str, ...] | tuple[Script, ...]) – Only get entries until this revision.

Return type:

list[Script]

stamp(target='heads')

Set the current database revision without running migrations.

Parameters:

target (str | Script | list[str] | list[Script] | tuple[str, ...] | tuple[Script, ...]) – Revision to set to.

Return type:

None

upgrade(target='heads')

Run migrations to upgrade database.

Parameters:

target (int | str | Script) – Revision to go up to.

Return type:

None

downgrade(target=-1)

Run migrations to downgrade database.

Parameters:

target (int | str | Script) – Revision to go down to.

Return type:

None

revision(message, empty=False, branch='default', parent='head', splice=False, depend=None, label=None, path=None)

Create a new revision. By default, auto-generate operations by comparing models and database.

Parameters:

• message (str) – Description of revision.

• empty (bool) – Don’t auto-generate operations.

• branch (str) – Use this independent branch name.

• parent (str | Script | list[str] | list[Script] | tuple[str, ...] | tuple[Script, ...]) – Parent revision(s) of this revision.

• splice (bool) – Allow non-head parent revision.

• depend (str | Script | list[str] | list[Script] | tuple[str, ...] | tuple[Script, ...] | None) – Revision(s) this revision depends on.

• label (str | list[str] | None) – Label(s) to apply to this revision.

• path (str | None) – Where to store this revision.

Returns:

List of new revisions.

Return type:

list[Script | None]

merge(revisions='heads', message=None, label=None)

Create a merge revision.

Parameters:

• revisions (str | Script | list[str] | list[Script] | tuple[str, ...] | tuple[Script, ...]) – Revisions to merge.

• message (str | None) – Description of merge, will default to revisions param.

• label (str | list[str] | None) – Label(s) to apply to this revision.

Returns:

A new revision object.

Return type:

Script | None

produce_migrations()

Generate the MigrationScript object that would generate a new revision.

Return type:

MigrationScript

needs_revision()

Check if any changes between the database and models are detected.

Returns:

True if changes are detected.

Return type:

bool

Added in version 3.2.

compare_metadata()

Describe the operations that would be present in a new revision.

This only supports a single database. For multiple databases, use the following instead:

for ops in alembic.produce_migrations().upgrade_ops_list:
    name = ops.upgrade_token.removesuffix("_upgrades")
    diff = ops.as_diffs()

Return type:

list[tuple[Any, …]]