The Alembic Textbook

This is the Alembic textbook. Pairs with SQLAlchemy , Postgres-focused SQLAlchemy , and FastAPI .

Alembic Textbook Ch. 1 — Introduction and Setup

Alembic basics: setup with SQLAlchemy 2.0, env.py for sync/async, naming conventions, the migration directory.

Alembic Textbook Ch. 2 — Autogenerate: What It Sees, What It Misses

What Alembic autogenerate detects (tables, columns, indexes, constraints) and what it doesn’t (data migrations, complex changes, defaults), plus a review checklist.

Alembic Textbook Ch. 3 — Writing Migrations Manually

Manual migrations: op API, ALTER patterns, batch ops for SQLite, data migrations, idempotent migrations.

Alembic Textbook Ch. 4 — Branching, Merging, and Multiple Heads

Alembic branching: how multiple revisions create branches, merging strategies, and team workflows.

Alembic Textbook Ch. 5 — Online Schema Changes (Zero-Downtime Patterns)

Zero-downtime migrations: expand-contract, batched backfills, CONCURRENTLY, NOT VALID FK, and pg_repack.

Alembic Textbook Ch. 6 — Multi-Database and Multi-Tenant Migrations

Multi-DB migrations via Alembic: -t multidb template, schema-per-tenant strategies, parallelism.

Alembic Textbook Ch. 7 — CI Integration

Alembic CI patterns: drift detection, migration round-trip tests, dry-run, deploy gates, and pre-merge checks.

Alembic Textbook Ch. 8 — Production Patterns and Recovery

Production Alembic: deploy strategies, recovery from broken migrations, stamp, manual fixes, and the operational checklist.