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')

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.

init_app(app, run_mkdir=None, command_name=None)

Register this extension on an app. Will automatically set up migration directory by default.

Keyword arguments on this method override those set during __init__() if not None.

Parameters:

• app (Flask) – App to register.

• run_mkdir (bool | None) – Run mkdir() automatically.

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

Return type:

None

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_context: MigrationContext

Get the Alembic MigrationContext for the current app.

Accessing this property opens a database connection but can’t close it automatically. Make sure to call migration_context.connection.close() when you’re done.

property op: Operations

Get the Alembic Operations context for the current app.

Accessing this property opens a database connection but can’t close it automatically. Make sure to call migration_context.connection.close() when you’re done.

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

mkdir()

Create the script directory and template.

Return type:

None

current()

Get the list of current revisions.

Return type:

tuple[Script, …]

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 (t_rev) – Parent revision(s) of this revision.

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

• depend (t_rev | 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

compare_metadata()

Generate a list of operations that would be present in a new revision.

Return type:

list[tuple[Any, …]]