alembic-gauntlet

Testing toolkit for Alembic migrations — run your migrations through the gauntlet

Tip

Building this with an AI assistant? Hand it one page instead of the whole site: the fixtures and helpers you actually get, the env.py contract the tests depend on, the rules that break a suite when they are broken, the mistakes models make with this API, and a map of which page to fetch for the rest. Every docs page is also served as raw Markdown at its own URL, and a Copy page button at the top of each one hands it straight to a chat window.

Installation

pip install "alembic-gauntlet[asyncio]"

The asyncio extra installs pytest-asyncio, which is not optional in practice: the inherited tests and both async fixtures are plain async def, so a suite without it errors out instead of running. It also has to be in auto mode:

# pyproject.toml
[tool.pytest.ini_options]
asyncio_mode = "auto"

Requirements: Python 3.10+, PostgreSQL, and an async driver such as asyncpg

Quick start

import pytest
from alembic_gauntlet import MigrationTestBase
from sqlalchemy import MetaData
from myapp.db import Base


@pytest.mark.integration
class TestMyMigrations(MigrationTestBase):
    """All seven tests inherited automatically."""

    @pytest.fixture
    def orm_metadata(self) -> MetaData:
        return Base.metadata

    @pytest.fixture(scope="session")
    def migration_db_url(self) -> str:
        return "postgresql+asyncpg://user:pass@localhost/testdb"

That's it! You now have:

• test_stairway_upgrade_downgrade — each migration forward and back
• test_migrations_up_to_date — schema matches ORM models
• test_check_constraints_match — CHECK constraints match ORM models, by name
• test_enum_values_match — enum values match ORM models, in order
• test_single_head_revision — no unmerged branches
• test_downgrade_all_the_way — full downgrade to base
• test_naming_conventions — indexes and FKs follow conventions

Documentation

Full documentation at bedrock-python.github.io/alembic-gauntlet.

• For AI agents — the whole library on one page, written for a coding assistant.

License

Apache 2.0 — see LICENSE.