Migrations: evolving your schema without downtime

Your first CREATE TABLE is easy. What about the third time you change users in production, without dropping the table?

That's Alembic. Every schema change gets a numbered, reviewable, revertible Python file.

The mental model

• Each revision is a file with upgrade() (apply) and downgrade() (undo).
• Alembic keeps a alembic_version table in your DB with the current head.
• alembic upgrade head fast-forwards from wherever you are to the latest.

Autogenerate — the killer feature

alembic revision --autogenerate -m "add plan column"

Alembic diffs your Python models against the live DB and writes the migration for you. Then you review it — autogen is 90% right; the other 10% is where prod outages come from.

The 5 rules of safe migrations

1. Add columns nullable first, backfill, then set NOT NULL — otherwise deploys with old code crash.
2. Never drop a column in the same release that removes it from code — deploy in two steps.
3. Rename with expand-contract — add new column, copy data, dual-write, remove old. Never a straight rename in prod.
4. Big table? Add index CONCURRENTLY on Postgres — regular CREATE INDEX locks writes.
5. Test the downgrade locally — running alembic downgrade -1 after every upgrade catches half of the bugs.

Try it (locally)

1. Change a model — add bio: Mapped[str | None].
2. alembic revision --autogenerate -m "add bio".
3. alembic upgrade head, then alembic downgrade -1.