Skip to content

alembic-gauntlet

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

alembic-gauntlet provides comprehensive testing for your Alembic database migrations with minimal setup. Get stairway tests, schema consistency checks, naming convention validation, and more — all in one base class.

Features

✅ Stairway tests — verify every migration can upgrade and downgrade
✅ Schema consistency — ensure migrations match your ORM models
✅ CHECK constraints and enum values — compared where autogenerate does not look
✅ Naming conventions — validate index and foreign key names
✅ Branch detection — catch unmerged migration branches
✅ Isolated schemas — parallel-safe test execution
✅ Testcontainers support — optional PostgreSQL container management

Installation

pip install "alembic-gauntlet[asyncio]"

The asyncio extra installs pytest-asyncio, which every consumer needs: 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"
asyncio_default_fixture_loop_scope = "function"

Optional dependencies: 

pip install "alembic-gauntlet[testcontainers]"  # Auto-managed PostgreSQL container

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

Quick example

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

Next steps

Why alembic-gauntlet?

Alembic migrations are powerful but error-prone. Common issues:

  • ❌ Migration works forward but breaks on downgrade
  • ❌ Forgot to run alembic revision --autogenerate after model changes
  • ❌ A CHECK constraint or an enum value the migration got wrong and autogenerate never reports
  • ❌ Unmerged migration branches cause conflicts
  • ❌ Inconsistent naming breaks your team's conventions

alembic-gauntlet catches all of these automatically. Write your migrations, inherit from MigrationTestBase, and let the gauntlet do its job.

License

Apache 2.0 — see LICENSE.