alembic downgrade: Revert Revisions
alembic downgrade <target> reverts revisions using their downgrade() functions, back to a revision, a relative offset, or base.
downgrade is the rollback half of Alembic. It runs the downgrade() of each revision in reverse until it reaches the target.
What it does
alembic downgrade runs the downgrade() function of each applied revision in reverse order down to the target. downgrade -1 reverts one revision; downgrade base reverts all of them; downgrade <rev> stops at a specific revision.
Common usage
# revert the most recent revision
alembic downgrade -1
# revert to a specific revision
alembic downgrade ae1027a6acf
# revert everything
alembic downgrade baseOptions
| Arg | What it does |
|---|---|
| downgrade -1 | Revert one revision |
| downgrade <rev> | Revert down to a specific revision id |
| downgrade base | Revert all revisions |
| -c <alembic.ini> | Config file path |
In CI
downgrade only works when each revision has a real downgrade() body; autogenerated ones often do, but hand-written data migrations may leave downgrade() as pass, making rollback a no-op. Treat downgrade as recovery on ephemeral databases, and prefer a forward fix in production pipelines.
Common errors in CI
"Can't locate revision identified by 'X'" means the target revision id is not in the code. "Relative revision -1 didn't produce N migrations" means you asked to step back further than the history allows. A downgrade() that only contains pass silently reverts nothing, so the schema stays put despite the command succeeding.