alembic-gauntlet

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

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 five 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_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.