Alembic Cheat Sheet

1Install & init1.19

pip install alembic★
Pulls in SQLAlchemy. Gives you the alembic CLI.
alembic init alembic★
Scaffolds the migration env once per project: creates alembic.ini, the alembic/ dir with env.py, and an empty versions/ folder for scripts.
alembic init -t async alembicasync
Use the async template when your app runs on asyncio (asyncpg, aiosqlite) — env.py is generated with an async engine.
alembic -c path/to/alembic.ini <cmd>
-c points at a non-default config; -n selects a named section for multi-DB setups.

2Wire up env.pyconnect models + DB

# alembic.ini sqlalchemy.url = postgresql+psycopg://user:pass@host/db★
The DB connection. Fine for local dev — but for apps, don't hardcode secrets here (see next).
# env.py — set the URL from your app/settings config.set_main_option("sqlalchemy.url", os.environ["DATABASE_URL"])★
Override the ini value at runtime so migrations use the same env-driven URL as your app.
# env.py — the key line for autogenerate from myapp.models import Base target_metadata = Base.metadata★
Autogenerate compares this MetaData to the DB. For SQLModel use SQLModel.metadata. Import every model module so all tables are registered.
context.configure(..., compare_type=True, compare_server_default=True)
Off by default. Turn on so autogenerate also detects column type and server-default changes.

3Create revisionsthe migration loop

alembic revision --autogenerate -m "add users table"★
The everyday command. Diffs target_metadata vs the DB and writes a script in versions/. Always open and review it before applying.
alembic revision -m "custom change"
Creates an empty revision to hand-write — for data migrations or anything autogenerate can't infer.
# versions/xxxx_add_users_table.py revision = "a1b2c3d4" down_revision = "9f8e7d6c" # parent; None for the first def upgrade(): ... def downgrade(): ...★
Each script is a node in a linked list. down_revision chains it to its parent (a GUID, not a sequence number — so branches merge cleanly).

4op.* operationsinside upgrade()/downgrade()

import sqlalchemy as sa from alembic import op op.create_table("user", sa.Column("id", sa.Integer, primary_key=True), sa.Column("name", sa.String(50), nullable=False))★
op is the schema-change API. create_table / drop_table mirror SQLAlchemy Column definitions.
op.add_column("user", sa.Column("age", sa.Integer(), nullable=True)) op.drop_column("user", "age")★
The most common pair. New columns on a populated table should be nullable=True or carry a server_default.
op.alter_column("user", "name", new_column_name="full_name", type_=sa.String(100), nullable=False)
Rename / retype / change nullability. Provide existing_type= on some backends for a clean rollback.
op.create_index("ix_user_name", "user", ["name"]) op.create_foreign_key("fk_hero_team", "hero", "team", ["team_id"], ["id"])
Also drop_index, create_unique_constraint, create_check_constraint, rename_table.

5Apply & roll backupgrade / downgrade

alembic upgrade head★
Apply all pending migrations to the newest revision. This is what you run on deploy.
alembic upgrade +1 · alembic upgrade a1b2c3d4
Step forward one revision, or up to a specific revision id / partial id.
alembic downgrade -1 · alembic downgrade base★
Roll back one step, or all the way to empty (base). Relies on your downgrade() being correct.
alembic upgrade head --sql > migrate.sqloffline
Offline mode: emit the SQL instead of running it — hand to a DBA or run in a controlled deploy. Also upgrade <from>:<to> --sql.

6Data & batch (SQLite)data migrations + ALTER on SQLite

op.execute("UPDATE user SET status = 'active' WHERE status IS NULL")★
Data migration via raw SQL. Run it in a hand-written revision after the schema op it depends on.
op.bulk_insert(user_table, [{"name": "admin"}, {"name": "guest"}])
Seed rows. Define a lightweight sa.table(...)/sa.column(...) literal for the target — don't import your live ORM model (it may drift from this revision).
with op.batch_alter_table("user") as batch: batch.add_column(sa.Column("age", sa.Integer())) batch.alter_column("name", nullable=False)★
SQLite can't ALTER most things. Batch mode rebuilds the table (create‑copy‑drop‑rename) so alters work. Set render_as_batch=True in env.py to autogenerate these.

7Inspect & navigatewhere am I?

alembic current★
Which revision the DB is at. Reads the alembic_version table. Add -v for detail.
alembic history --verbose · alembic history -r -3:current★
The revision graph, newest first. Use a range (-r) to focus. alembic show <rev> for one script's details.
alembic heads · alembic branches
heads lists the tip(s) — more than one means the history has branched and needs a merge (card 8).
alembic stamp head · alembic stamp a1b2c3d4no SQL run
Marks the DB as at a revision WITHOUT running migrations. For adopting Alembic on an existing schema, or fixing a mismatched version pointer.

8Branches & mergesdivergent history

alembic merge -m "merge heads" heads★
When two branches both add a revision (e.g. two devs), you get multiple heads. merge writes a revision with both as parents so upgrade head works again.
alembic revision -m "feature x" --head=a1b2c3d4 --branch-label=featx
Deliberately branch from a specific revision and label it; reference later as featx@head.
depends_on = "other_rev" # in the script, cross-branch ordering
Force this revision to run after another even across branches (e.g. a shared enum type both need).

!Common gotchasread before shipping

ALWAYS review autogenerate
It's a draft, not truth. A rename shows up as drop + add = data loss. Read and edit every generated script before committing.
autogenerate misses things
It won't detect table/column renames; without compare_type/compare_server_default it skips type & default changes. It also needs all models imported into target_metadata.
SQLite can't ALTER
Bare alter_column/drop_column fail on SQLite. Wrap in op.batch_alter_table(...) (or render_as_batch=True).
write real downgrade()
A rollback is only as good as your downgrade(). Autogenerate's guess can be wrong — verify it, and test downgrade before you rely on it.
never edit an applied migration
Once a revision has run anywhere (esp. prod), it's immutable. Fix forward with a new revision, don't rewrite history.
multiple heads block upgrade
upgrade head errors if history branched. Run alembic heads, then alembic merge heads.
don't import live ORM models in data migrations
Models evolve; a revision must reflect the schema at its point in time. Use local sa.table()/sa.column() literals for bulk_insert.

Alembic cheat sheet