alembic-utils-extended 1.2.0

A sqlalchemy/alembic extension for migrating entities like functions, triggers, views, materialized views, and check constraints.

Alembic Utils Extended

Autogenerate Support for PostgreSQL Functions, Views, Materialized Views, Triggers, Policies, and Check Constraints

This is a fork of the much more popular alembic_utils package to extend the capabilities of Alembic, which adds support for autogenerating a larger number of PostgreSQL entity types, including functions, views, materialized views, triggers, and policies.

This repo adds additional support for defining indices for materialized views and autogenerating check constraints.

Quickstart

Visit the quickstart guide for usage instructions.

Entity Registration

# migrations/env.py

from alembic_utils_extended.pg_view import PGView
from alembic_utils_extended.replaceable_entity import register_entities

view = PGView(schema="public", signature="view", definition="SELECT 1")
register_entities([view])

Monitor Check Constraints

Check constraints defined in SQLAlchemy models can also be autogenerated. Note that check constraints must be named. Add to your env.py:

# migrations/env.py
from alembic import context

context.configure(
    # ... other configurations ...
    compare_check_constraints=True,
)

Monitor Expression Indexes

Alembic's built-in autogenerate silently skips expression indexes (Index("ix_foo", func.lower(table.c.x))) because it can't reliably reflect functional-index definitions from pg_indexes. With compare_expression_indexes=True, alembic_utils_extended detects new and removed expression indexes by name and emits the corresponding op.create_index / op.drop_index. Expression indexes must be named.

# migrations/env.py
from alembic import context

context.configure(
    # ... other configurations ...
    compare_expression_indexes=True,
)

Content changes under a stable name are not detected. Comparison is identity-only ((table_name, index_name) set diff). If the same index name exists in both the model and the database, autogenerate raises rather than silently miss an expression change — to evolve the expression, rename the index (which produces a drop + create).

Common pitfalls the comparator catches at autogenerate time:

• func.X("col_name") anti-pattern — bare strings inside func.X(...) are treated as bound-parameter literal values, not column references. The resulting index is on the constant string, not the column. Use func.X(table.c.col_name) or func.X(literal_column("col_name")) instead. The comparator raises with a remediation hint when it detects this.

Autogeneration

The next time you autogenerate a revision, Alembic will detect if your entities are new, updated, or removed and populate the migration script.

alembic revision --autogenerate -m 'message'

Contributing

If you have any issues with contributing, please reach out to [e-mail] so that we can work out any issues you are having! This is mostly just forked directly from alembic_utils, so it's possible something is misconfigured.

Testing

poetry install
poetry run pre-commit run --all-files
poetry run pytest