davidism / flask-alembic

Flask extension to integrate Alembic with Flask-SQLAlchemy.

Flask-Alembic

Flask-Alembic is a Flask extension that provides a configurable Alembic migration environment around a Flask-SQLAlchemy database.

Installation

Install from PyPI:

$ pip install Flask-Alembic

Basic Usage

You've created a Flask application and some models with Flask-SQLAlchemy. Now start using Flask-Alembic:

from flask_alembic import Alembic

# Intialize the extension
alembic = Alembic()
alembic.init_app(app)

Commands are added to the flask CLI:

$ flask db --help
$ flask db revision "making changes"
$ flask db upgrade

You can also access Alembic's functionality from Python:

with app.app_context():
    # Auto-generate a migration
    alembic.revision('making changes')

    # Upgrade the database
    alembic.upgrade()

    # Access the internals
    environment_context = alembic.env

Differences from Alembic

• Configuration is taken from Flask.config instead of alembic.ini and env.py.
• The migrations are stored directly in the migrations folder instead of the versions folder.
• Provides the migration environment instead of env.py and exposes Alembic's internal API objects.
• Differentiates between CLI commands and Python functions. The functions return revision objects and don't print to stdout.
• Allows operating Alembic at any API level while the app is running, through the exposed objects and functions.
• Does not (currently) support offline migrations. I don't plan to add this but am open to patches.
• Does not (currently) support multiple databases. I plan on adding support for Flask-SQLAlchemy binds and external bases eventually, or am open to patches.
• Adds a system for managing independent migration branches and makes it easier to work with named branches.

flask-alembic's Issues

How to configure alembic to use `render_as_batch=True`

Good day,

I need to use alembic render_as_batch feature. However, I tried using

ALEMBIC_CONTEXT = {
    "render_as_batch": True
}

and it did not work. What am I missing? how may I enable this feature?

Thank you

BitBucket or GitHub?

The docs say:

The latest code is hosted on BitBucket.

But the docs also include "Edit on GitHub" and the code is here. Maybe they are mirrored? Just thought I'd mention the possible confusion.

CLI downgrade command raises exception

When calling db downgrade without any arguments from my Flask app, I get following:

  File "my_project/.venv/lib/python3.11/site-packages/flask_alembic/cli.py", line 118, in downgrade
    alembic.downgrade(target)
  File "my_project/.venv/lib/python3.11/site-packages/flask_alembic/extension.py", line 408, in downgrade
    self.run_migrations(do_downgrade)
  File "my_project/.venv/lib/python3.11/site-packages/flask_alembic/extension.py", line 272, in run_migrations
    env.run_migrations(**kwargs)
  File "my_project/.venv/lib/python3.11/site-packages/alembic/runtime/environment.py", line 948, in run_migrations
    self.get_context().run_migrations(**kw)
  File "my_project/.venv/lib/python3.11/site-packages/alembic/runtime/migration.py", line 615, in run_migrations
    for step in self._migrations_fn(heads, self):
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "my_project/.venv/lib/python3.11/site-packages/flask_alembic/extension.py", line 403, in do_downgrade
    return self.script_directory._downgrade_revs(  # type: ignore[return-value]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "my_project/.venv/lib/python3.11/site-packages/alembic/script/base.py", line 473, in _downgrade_revs
    return [
           ^
  File "my_project/.venv/lib/python3.11/site-packages/alembic/script/base.py", line 473, in <listcomp>
    return [
           ^
  File "my_project/.venv/lib/python3.11/site-packages/alembic/script/revision.py", line 813, in iterate_revisions
    revisions, heads = fn(
                       ^^^
  File "my_project/.venv/lib/python3.11/site-packages/alembic/script/revision.py", line 1330, in _collect_downgrade_revisions
    branch_label, target_revision = self._parse_downgrade_target(
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "my_project/.venv/lib/python3.11/site-packages/alembic/script/revision.py", line 1112, in _parse_downgrade_target
    assert isinstance(
AssertionError: Expected downgrade target in string form

I did some debugging to ensure that alembic.downgrade(target) is called with default argument and it looks like this:

alembic.downgrade("-1")

problem happens here:

# flask-alembic/extension.py
def downgrade(self, target: int | str | Script = -1) -> None:
    """Run migrations to downgrade database.

    :param target: Revision to go down to.
    """
    target_arg = self._simplify_rev(target, handle_int=True)

    def do_downgrade(
        revision: str | list[str] | tuple[str, ...], context: MigrationContext
    ) -> list[MigrationStep]:
        return self.script_directory._downgrade_revs(  # type: ignore[return-value]
            target_arg,  # type: ignore[arg-type]
            revision,  # type: ignore[arg-type]
        )

self._simplify_rev() always returns list of strings, but notice that method _downgrade_revs in alembic is declared as following:

# alembic/script/base.py
def _downgrade_revs(
    self, destination: str, current_rev: Optional[str]
) -> List[RevisionStep]:
    ...

No time to dig deeper, hope that above helps.