Flask-Alembic

https://flask-alembic.readthedocs.io/
Admin
Flask-Alembic is a Flask extension that provides a configurable Alembic database migration...
Tokens:5,721
Snippets:43
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Configure Flask-Alembic with Flask-SQLAlchemy-Lite

Source: https://flask-alembic.readthedocs.io/en/stable/databases

Example of initializing Flask-Alembic when using Flask-SQLAlchemy-Lite. This requires passing the metadata explicitly to the Alembic constructor, as Flask-SQLAlchemy-Lite does not manage it itself.

```python
from flask_alembic import Alembic
from sqlalchemy.orm import DeclarativeBase

class Model(DeclarativeBase):
    pass

alembic = Alembic(metadatas=Model.metadata)

```

--------------------------------

### Install Flask-Alembic using pip

Source: https://flask-alembic.readthedocs.io/index

This snippet shows how to install the Flask-Alembic package using pip, a standard Python package installer. Ensure you have pip installed and accessible in your environment.

```bash
pip install Flask-Alembic

```

--------------------------------

### Configure pre-commit Hooks Post-Write

Source: https://flask-alembic.readthedocs.io/en/stable/config

This example configures Flask-Alembic to run all defined 'pre-commit' hooks after a migration file is written. It specifies the hook, type, entry point, and options to run the pre-commit hooks on the generated file. This integrates pre-commit into the migration workflow.

```python
ALEMBIC = {
    "post_write_hooks": {
        "hooks": "pre-commit",
        "pre-commit.type": "console_scripts",
        "pre-commit.entrypoint": "pre-commit",
        "pre-commit.options": "run --files REVISION_SCRIPT_FILENAME"
    }
}
```

--------------------------------

### Alembic Metadata Comparison

Source: https://flask-alembic.readthedocs.io/en/stable/api

This function compares the database metadata with the current models to describe the operations needed for a new revision. It's useful for understanding potential schema changes before applying them. For multi-database setups, a specific iteration pattern is provided.

```python
def 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()
    """
    pass
```

--------------------------------

### Initialize Flask-Alembic with an App

Source: https://flask-alembic.readthedocs.io/en/stable/use

Demonstrates the standard Flask extension pattern for initializing Flask-Alembic, either by passing the app directly or using an init_app method. This is essential for integrating Flask-Alembic into your Flask application.

```python
from flask_alembic import Alembic

alembic = Alembic()
alembic.init_app(app)  # call in the app factory if you're using that pattern
```

--------------------------------

### Configure Flask-Alembic with Plain SQLAlchemy

Source: https://flask-alembic.readthedocs.io/en/stable/databases

Demonstrates initializing Flask-Alembic with plain SQLAlchemy, where engines and metadata are defined manually. This allows explicit control over the database connection and models used for migrations.

```python
from flask_alembic import Alembic
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase

engine = create_engine("sqlite:///default.sqlite")

class Model(DeclarativeBase):
    pass

alembic = Alembic(metadatas=Model.metadata, engines=engine)

```

--------------------------------

### Initialize Flask-Alembic with SQLAlchemy Metadata

Source: https://flask-alembic.readthedocs.io/en/stable/use

Shows how to initialize Flask-Alembic when using Flask-SQLAlchemy-Lite or plain SQLAlchemy, specifically when you need to provide custom metadata. This ensures Alembic correctly identifies your database models.

```python
from flask_alembic import Alembic
from sqlalchemy.orm import DeclarativeBase

class Model(DeclarativeBase):
    pass

alembic = Alembic(metadatas=Model.metadata)
```

--------------------------------

### Configure Flask-Alembic for Multiple Databases

Source: https://flask-alembic.readthedocs.io/en/stable/databases

Illustrates setting up Flask-Alembic to manage migrations across multiple databases. This involves defining multiple metadatas and engines, which will lead to the use of Alembic's 'multidb' template.

```python
from flask import Flask
from flask_alembic import Alembic
from flask_sqlalchemy_lite import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase

class DefaultBase(DeclarativeBase):
    pass

class AuthBase(DeclarativeBase):
    pass

db = SQLAlchemy()
alembic = Alembic(
    metadatas={
        "default": DefaultBase.metadata,
        "auth": AuthBase.metadata,
    },
)
app = Flask(__name__)
app.config["SQLALCHEMY_ENGINES"] = {
    "default": "sqlite:///default.sqlite",
    "auth": "postgresql:///app-auth",
}
db.init_app(app)
alembic.init_app(app)

```

--------------------------------

### Manage Alembic Migrations via Flask CLI

Source: https://flask-alembic.readthedocs.io/en/stable/use

Illustrates how to use Flask-Alembic commands through the Flask command-line interface. This includes generating new migration revisions and applying pending upgrades to the database.

```bash
$ flask db --help
$ flask db revision "made changes"
$ flask db upgrade
```

--------------------------------

### Apply All Available Alembic Upgrades from Python

Source: https://flask-alembic.readthedocs.io/en/stable/use

Shows the Python method for applying all pending database migrations. This is the programmatic equivalent of the `flask db upgrade` command, enabling in-app database schema updates.

```python
# run all available upgrades
# same as `flask db upgrade`
alembic.upgrade()
```

--------------------------------

### Configure git Add Post-Write Hook

Source: https://flask-alembic.readthedocs.io/en/stable/config

This configuration enables a 'git add' command as a post-write hook in Flask-Alembic, often used in conjunction with other hooks like pre-commit. It specifies the hook, its type as 'exec', the executable 'git', and options to add the migration file to git staging. This ensures newly generated migration files are automatically staged for commit.

```python
ALEMBIC = {
    "post_write_hooks": {
        "hooks": "pre-commit, git",
        "pre-commit.type": "console_scripts",
        "pre-commit.entrypoint": "pre-commit",
        "pre-commit.options": "run --files REVISION_SCRIPT_FILENAME",
        "git.type": "exec",
        "git.executable": "git",
        "git.options": "add REVISION_SCRIPT_FILENAME"
    }
}
```

--------------------------------

### Interact with Alembic Internals via Python

Source: https://flask-alembic.readthedocs.io/en/stable/use

Demonstrates accessing lower-level Alembic functionalities directly from Python code. This includes retrieving revision information, checking current revision status, and performing DDL operations like dropping columns, offering fine-grained control over migrations.

```python
# locate a revision by name
alembic.script.get_revision("head")

# could compare this to the "head" revision above to see if upgrades are needed
alembic.context.get_current_revision()

# probably don't want to do this outside a revision, but it'll work
alembic.op.drop_column("my_table", "my_column")

# see that the column you just dropped will be added back next revision
alembic.compare_metadata()
```

--------------------------------

### Configure Flask-Alembic with Multiple Metadatas

Source: https://flask-alembic.readthedocs.io/en/stable/databases

Shows how to configure Flask-Alembic when models for a single database are split across multiple SQLAlchemy metadatas. A list of metadatas can be passed directly to the 'metadatas' argument.

```python
from flask_alembic import Alembic
from sqlalchemy.orm import DeclarativeBase

class DefaultBase(DeclarativeBase):
    pass

class AuthBase(DeclarativeBase):
    pass

alembic = Alembic(metadatas=[DefaultBase.metadata, AuthBase.metadata])

```

--------------------------------

### Configure ruff Formatter Post-Write Hook

Source: https://flask-alembic.readthedocs.io/en/stable/config

This configuration sets up the 'ruff' formatter as a post-write hook for Flask-Alembic migrations. It defines the hook, its type, entry point, and specific options to format the revision script file. This automates code formatting with ruff.

```python
ALEMBIC = {
    "post_write_hooks": {
        "hooks": "ruff",
        "ruff.type": "console_scripts",
        "ruff.entrypoint": "ruff",
        "ruff.options": "format REVISION_SCRIPT_FILENAME"
    }
}
```

--------------------------------

### Execute Alembic Commands within App Context

Source: https://flask-alembic.readthedocs.io/en/stable/use

Explains the necessity of an application context when running Alembic commands programmatically outside of a web request. This ensures that Flask-Alembic can access the application's configuration and resources correctly.

```python
with app.app_context():
    alembic.upgrade()
```

--------------------------------

### Alembic Database Migration Operations

Source: https://flask-alembic.readthedocs.io/en/stable/api

This section details core Alembic commands for managing database migrations. It covers operations like creating new revisions, applying upgrades and downgrades, stamping versions, and merging migration branches. These functions interact with the Alembic script directory and database to manage schema evolution.

```python
def branches():
    """
    Get the list of revisions that have more than one next revision.
    """
    pass

def log(_start ='base'_, _end ='heads'_) :
    """
    Get the list of revisions in the order they will run.
    Parameters:
      start: Only get entries since this revision.
      end: Only get entries until this revision.
    """
    pass

def stamp(_target ='heads'_) :
    """
    Set the current database revision without running migrations.
    Parameters:
      target: Revision to set to.
    """
    pass

def upgrade(_target ='heads'_) :
    """
    Run migrations to upgrade database.
    Parameters:
      target: Revision to go up to.
    """
    pass

def downgrade(_target =-1_) :
    """
    Run migrations to downgrade database.
    Parameters:
      target: Revision to go down to.
    """
    pass

def 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: Description of revision.
      empty: Don’t auto-generate operations.
      branch: Use this independent branch name.
      parent: Parent revision(s) of this revision.
      splice: Allow non-head parent revision.
      depend: Revision(s) this revision depends on.
      label: Label(s) to apply to this revision.
      path: Where to store this revision.
    Returns:
      List of new revisions.
    """
    pass

def merge(_revisions ='heads'_, _message =None_, _label =None_) :
    """
    Create a merge revision.
    Parameters:
      revisions: Revisions to merge.
      message: Description of merge, will default to `revisions` param.
      label: Label(s) to apply to this revision.
    Returns:
      A new revision object.
    """
    pass

def produce_migrations() :
    """
    Generate the `MigrationScript` object that would generate a new revision.
    """
    pass

def needs_revision() :
    """
    Check if any changes between the database and models are detected.
    Returns:
      True if changes are detected.
    """
    pass
```

--------------------------------

### Generate a New Alembic Revision from Python

Source: https://flask-alembic.readthedocs.io/en/stable/use

Provides the Python equivalent of the `flask db revision` command. This allows programmatic generation of new database migration scripts, useful for automated workflows or complex application logic.

```python
# generate a new revision
# same as `flask db revision "made changes"`
alembic.revision("made changes")
```

--------------------------------

### Configure black Formatter Post-Write Hook

Source: https://flask-alembic.readthedocs.io/en/stable/config

This snippet configures Flask-Alembic to use the 'black' formatter as a post-write hook for generated migration files. It specifies the hook type and entry point. This ensures migration files are automatically formatted by black after creation.

```python
ALEMBIC = {
    "post_write_hooks": {
        "hooks": "black",
        "black.type": "console_scripts",
        "black.entrypoint": "black"
    }
}
```

--------------------------------

### Configure Flask-Alembic Version Locations

Source: https://flask-alembic.readthedocs.io/en/stable/branches

This configuration snippet demonstrates how to set up multiple version locations for Alembic migrations using Flask-Alembic. It allows specifying directories for migration scripts, including named branches with associated directories. Relative paths are resolved from the application root.

```python
ALEMBIC = {
    "version_locations": [
        # not a branch, just another search location
        "other_migrations",
        # posts branch migrations will be placed here
        ("posts", "/path/to/posts_extension/migrations"),
        # relative paths are relative to the application root
        ("users", "users/migrations"),
    ],
}

```

--------------------------------

### Flask-Alembic Alembic Class API

Source: https://flask-alembic.readthedocs.io/en/stable/api

This section details the methods and properties of the Alembic class, which provides the core functionality for managing Alembic migrations within a Flask application.

```APIDOC
## Flask-Alembic Alembic Class

### Description
Provides an Alembic environment and migration API. It can be instantiated with an app instance or initialized later using `init_app()`.

### Initialization Parameters

*   **app** (_Flask_ | _None_) – The Flask app instance to register the extension with.
*   **run_mkdir** (_bool_) – If True, runs `mkdir()` during `init_app`. Keyword-only since version 3.1.
*   **command_name** (_str_) – The name to register a Click command with during `init_app`. If empty, no command is registered. Keyword-only since version 3.1.
*   **metadatas** (_sa.MetaData_ | _list_[sa.MetaData] | _dict_[str, sa.MetaData | list[sa.MetaData]] | _None_) – Metadata objects to inspect for generating migrations. A single metadata or list is assigned to the "default" key. A dictionary can map keys to multiple metadatas. Defaults to `db.metadata` if using Flask-SQLAlchemy.
*   **engines** (_sa.Engine_ | _dict_[str, sa.Engine] | _None_) – Engines to perform migrations on, matching keys in `metadatas`. A single engine is assigned to the "default" key. A dictionary can map keys to specific engines. Defaults to `db.engines` if using Flask-SQLAlchemy(-Lite).

### Methods

#### `init_app(app)`

*   **Description:** Registers the Alembic extension with a Flask app.
*   **Parameters:**
    *   **app** (_Flask_) - The Flask app to register with.
*   **Return type:** None

#### `rev_id()`

*   **Description:** Generates a unique ID for a revision. By default, uses the current UTC timestamp. Can be overridden.
*   **Return type:** str

#### `run_migrations(fn, **kwargs)`

*   **Description:** Configures an Alembic `MigrationContext` to run migrations for a given function, acting as a replacement for Alembic's `env.py` `run_migrations_online`.
*   **Parameters:**
    *   **fn** (_Callable_) - A function to control which migrations are run.
    *   **kwargs** (_Any_) - Extra arguments passed to `upgrade` or `downgrade`.
*   **Return type:** None

#### `mkdir()`

*   **Description:** Creates the script directory and template. Uses the `generic` template for single databases and `multidb` for multiple databases.
*   **Return type:** None

#### `current()`

*   **Description:** Gets the list of current migration revision IDs.
*   **Return type:** tuple[_Script_, ...]

#### `needs_upgrade()`

*   **Description:** Checks if the current database revisions are the latest head revisions.
*   **Returns:** `True` if the database is not at the latest revisions, `False` otherwise.
*   **Return type:** bool

#### `heads(resolve_dependencies=False)`

*   **Description:** Gets the list of revision IDs that have no child revisions (the head revisions).
*   **Parameters:**
    *   **resolve_dependencies** (_bool_) - Whether to resolve dependencies.

### Properties

*   **`config`** (_Config_): Get the Alembic `Config` for the current app.
*   **`script_directory`** (_ScriptDirectory_): Get the Alembic `ScriptDirectory` for the current app.
*   **`environment_context`** (_EnvironmentContext_): Get the Alembic `EnvironmentContext` for the current app.
*   **`migration_contexts`** (_dict_[str, MigrationContext]_): Get a map of Alembic `MigrationContext` for each configured database key. Context connections are closed when the Flask app context ends. Added in version 3.1.
*   **`migration_context`** (_MigrationContext_): Get the Alembic `MigrationContext` for the current app. For multiple databases, this is the context for the "default" key. The context connection is closed when the Flask app context ends.
*   **`ops`** (_dict_[str, Operations]_): Get the Alembic `Operations` context for each configured database key. Added in version 3.1.
*   **`op`** (_Operations_): Get the Alembic `Operations` context for the current app. For multiple databases, this is the context for the "default" key.
```

--------------------------------

### Create a New Alembic Revision with a Branch

Source: https://flask-alembic.readthedocs.io/en/stable/branches

This section shows how to use the Flask-Alembic `revision` command to create new database migration scripts within a specific named branch. It simplifies the equivalent Alembic commands by abstracting `--parent`, `--label`, and `--path` options.

```bash
$ flask db revision --branch users "create user model"

# equivalent to (if branch is new)
$ alembic revision --autogenerate --head base --branch-label users --version-path users/migrations -m "create user model"

# or (if branch exists)
$ alembic revision --autogenerate --head users@head -m "create user model"

```
Tokens:
Raw