dalembic

Branch-aware Alembic deployment: STG downgrade-to-main, prod upgrade-to-head, reverts, and deploy state.

Not SQLAlchemy Alembic. SQLAlchemy: import alembic / alembic upgrade head. This package: import dalembic / dalembic.

Problems this solves

• Concurrent STG merges — Downgrade with the previous branch's migration code, then upgrade to the new head.
• Edited migration on the same branch — Redeploy after changing an unreleased revision; STG uses the prior commit's migration files to downgrade first.
• Abandoned MR on STG — Empty upgrade() (keep downgrade()), redeploy to roll back.
• Controlled reverts — Revert migration + ALEMBIC_REVERT_STAMP to run downgrade() and stamp a target revision.
• Deploy audit trail — STG records the last deployed commit SHA in Postgres dalembic_state.
• Prod stays simple — Production is still upgrade-to-head.

Install

uv add dalembic   # or: pip install dalembic

CI: use dalembic, not alembic upgrade head

Replace alembic upgrade head in deploy jobs with dalembic. It picks the Alembic operation from deploy state (ENV, commit SHA, last STG deploy, optional revert stamp).

Prod:

export ENV=prod DB_HOST=... DB_PORT=... DB_NAME=... DB_USER=... DB_PASSWORD=...
dalembic

STG (also set CI_COMMIT_SHA and main's head revision):

export ALEMBIC_HEAD_REVISION_MAIN=$(git show origin/main:migrations/versions/ | grep -oP '^\d{4}' | sort | tail -1)
export CI_COMMIT_SHA=$CI_COMMIT_SHA ENV=stg
dalembic

On STG, do not call alembic upgrade head directly — you lose downgrade-before-upgrade and deploy-state tracking.

Key environment variables

See DeploySettings in code for the full list.

Revert workflow (2-MR)

Reverting is lossy — review downgrade() bodies first.

MR 1: Add a migration calling revert_to, deploy with ALEMBIC_REVERT_STAMP=<target>.

from dalembic.revert import revert_to

def upgrade() -> None:
    revert_to("0002", from_revision="0005")

def downgrade() -> None:
    pass

MR 2: Remove the revert migration and ALEMBIC_REVERT_STAMP. Temporary revert: originals re-apply on deploy. Permanent revert: delete the original migrations too.

App startup (optional)

For embedded upgrades without STG state: dalembic.runtime.upgrade_head(Path("alembic.ini")).

Development

uv sync --all-extras
docker compose up -d
uv run pytest tests/unit tests/integration -q

pgAdmin: http://localhost:5050 (admin@admin.com / admin, server pre-configured).

License

MIT