Applying and Rolling Back Migrations

Applying migrations and rolling them back are the two most frequent Alembic operations. alembic upgrade head applies all pending migrations in order; alembic downgrade -1 rolls back the most recent one. Understanding the migration chain, how Alembic determines the current state, and how to safely handle rollbacks — including the case where downgrade is difficult or impossible — gives you the confidence to evolve your schema without fear.

Applying Migrations #

# ── Apply all pending migrations ──────────────────────────────────────────────
alembic upgrade head
# "head" means the latest migration in the chain
# Runs all unapplied migrations in order from current version to head

# ── Apply a specific number of steps ──────────────────────────────────────────
alembic upgrade +1    # apply the next one migration
alembic upgrade +2    # apply the next two migrations

# ── Apply up to a specific revision ───────────────────────────────────────────
alembic upgrade abc123def456   # apply up to and including this revision

# ── Preview the SQL without executing it ─────────────────────────────────────
alembic upgrade head --sql     # prints SQL to stdout, does not run it

# ── Check what would be applied ───────────────────────────────────────────────
alembic current         # show current applied revision
alembic history         # show all revisions with applied marker
alembic show abc123     # show details of a specific revision

Rolling Back #

# ── Roll back the most recent migration ──────────────────────────────────────
alembic downgrade -1

# ── Roll back two migrations ──────────────────────────────────────────────────
alembic downgrade -2

# ── Roll back to a specific revision ─────────────────────────────────────────
alembic downgrade abc123def456   # reverts to state at abc123def456

# ── Roll back ALL migrations (development/test only!) ─────────────────────────
alembic downgrade base   # NEVER in production — drops everything!

# ── Preview what downgrade SQL would run ─────────────────────────────────────
alembic downgrade -1 --sql

The Migration Chain #

Migration chain (each revision points to its parent):

base → rev001 → rev002 → rev003 → rev004 (head)
                                          ↑ current (alembic_version table)

alembic upgrade head:   applies nothing (already at head)
alembic downgrade -1:   reverts rev004, current becomes rev003
alembic downgrade -1:   reverts rev003, current becomes rev002
alembic upgrade head:   applies rev003 then rev004

# After a bad migration was applied:
# 1. alembic downgrade -1    ← revert the bad migration
# 2. Fix the migration script (or write a new one)
# 3. alembic upgrade head    ← reapply

Handling Irreversible Migrations #

from alembic.operations import MigrationScript

def upgrade() -> None:
    # Add a NOT NULL column with a default — fine to run
    op.add_column("posts", sa.Column("is_featured", sa.Boolean(),
                                     nullable=False, server_default="false"))
    # Remove server_default after data is populated (now truly NOT NULL)
    op.alter_column("posts", "is_featured", server_default=None)

def downgrade() -> None:
    op.drop_column("posts", "is_featured")

# ── Migration that loses data on downgrade ────────────────────────────────────
def upgrade() -> None:
    # Archive and then delete old data
    op.execute(
        "INSERT INTO post_archive SELECT * FROM posts WHERE deleted_at IS NOT NULL"
    )
    op.execute("DELETE FROM posts WHERE deleted_at IS NOT NULL")
    op.drop_column("posts", "deleted_at")

def downgrade() -> None:
    # Cannot restore deleted data — document this explicitly
    op.add_column("posts", sa.Column("deleted_at", sa.TIMESTAMP(timezone=True),
                                     nullable=True))
    # NOTE: data in post_archive could be restored here, but deleted rows are gone
    # This downgrade restores the column structure but NOT the deleted data

Common Mistakes #

Mistake 1 — Running downgrade base in the wrong environment #

❌ Wrong — drops all tables in production:

DATABASE_URL=postgresql://prod-db... alembic downgrade base   # destroys everything!

✅ Correct — always use specific revisions in production:

DATABASE_URL=postgresql://prod-db... alembic downgrade -1   # ✓ controlled rollback

Mistake 2 — Editing an already-applied migration #

❌ Wrong — changing a migration that has already run:

Editing alembic/versions/abc123_add_column.py after it was applied.
Alembic will not re-run it — the database now differs from the script!

✅ Correct — create a new migration to fix the issue. Never edit applied migrations.

Mistake 3 — Forgetting to write the downgrade function #

❌ Wrong — cannot roll back:

def downgrade() -> None:
    pass   # no rollback possible — dangerous in production!

✅ Correct — always implement a meaningful downgrade, even if it just logs a warning about data loss.

Quick Reference #