Alembic Cheatsheet

Quick Reference

# Initialise Alembic
alembic init alembic

# Create autogenerated migration with a specific message
alembic revision --autogenerate -m "add users table"

# Create empty manual migration
alembic revision -m "custom migration"

# Apply all pending migrations
alembic upgrade head

# Upgrade by one migration
alembic upgrade +1

# Roll back one migration
alembic downgrade -1

# Roll back all migrations
alembic downgrade base

# Check current DB revision
alembic current

# View migration history
alembic history -v

# Show migration heads
alembic heads

What is Alembic?

Alembic is the database migration tool commonly used with SQLAlchemy.

It helps you keep track of database schema changes over time, such as creating tables, adding columns, renaming fields, or creating indexes.

Instead of manually editing the database, you define or update your SQLAlchemy models, then generate a migration file that describes how to move the database schema forward or backward.

Tip (Mental Model)

Think of Alembic as version control for your database schema.

Your application code is tracked by Git, while your database structure is tracked by migration files.

Initial Setup

Initialise Alembic in a project with the following command.

alembic init alembic

This creates an alembic/ folder and an alembic.ini file.

my-project/
├── alembic/
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
└── alembic.ini

Important (Important)

After running alembic init, update alembic/env.py so Alembic can access your SQLAlchemy Base.metadata and database URL.

If this is not configured properly, Alembic may not detect your models during autogeneration.

Common Alembic Workflow

A typical migration workflow looks like this.

# 1. Change your SQLAlchemy models

# 2. Generate a migration file
alembic revision --autogenerate -m "add users table"

# 3. Review the generated migration file

# 4. Apply the migration to the database
alembic upgrade head

Warning (Always Review Autogenerated Migrations)

--autogenerate is helpful, but it is not perfect.

Always inspect the generated migration file before applying it, especially when changing column types, indexes, constraints, or relationships.

Create a New Migration

Autogenerate from SQLAlchemy models

alembic revision --autogenerate -m "add users table"

Use this after changing your SQLAlchemy models.

Alembic compares your current database schema with your model metadata and generates a migration file inside alembic/versions/.

Create an empty migration manually

alembic revision -m "add custom migration"

Use this when you want to write the migration yourself.

This is useful for custom SQL, data migrations, or schema changes that Alembic cannot safely infer.

Apply Migrations

Apply all pending migrations, bringing your database schema up to the latest version. head here refers to the latest migration revision in your Alembic migration history.

alembic upgrade head

Upgrade to a specific revision.

alembic upgrade <revision_id>

Upgrade by one migration.

alembic upgrade +1

Roll Back Migrations

Roll back one migration.

alembic downgrade -1

Roll back to a specific revision.

alembic downgrade <revision_id>

Roll back all migrations.

alembic downgrade base

Warning (Be Careful with Downgrades)

Downgrades can be destructive if they drop columns, tables, or constraints.

Always check the downgrade() function in the migration file before running a rollback.

Inspect Migration State

Check the current database revision.

alembic current

View migration history.

alembic history

View detailed migration history.

alembic history -v

Show the latest migration head.

alembic heads

Show the base migration.

alembic show <revision_id>

Tip (Debugging Tip)

If your database is not behaving as expected, first check:

What migration revision your database is currently on.
What the latest migration head is.
Whether the expected migration file actually exists in alembic/versions/.