What Is Alembic? Database Migrations Explained
How Alembic tracks and applies versioned schema changes for SQLAlchemy projects, and why you need it the moment a database schema has to change
Alembic manages database schema changes over time for SQLAlchemy projects — versioned migration scripts you can apply, review, and roll back, instead of hand-editing a production schema directly.
The problem it solves
Once an application is running against a real database, changing the schema — adding a column, changing a type, adding an index — can’t just mean editing your models and hoping the database catches up. You need a record of what changed, in what order, and a way to apply that exact sequence of changes to any environment (local, staging, production) reliably. Alembic generates and manages that sequence as versioned migration scripts.
How it fits with SQLAlchemy
SQLAlchemy itself has no built-in migration system — Alembic, built by the same maintainer, is the standard tool that fills that gap. A typical workflow: change your SQLAlchemy models, run alembic revision --autogenerate to produce a draft migration script by diffing your models against the database’s current schema, review and adjust that script, then alembic upgrade head to apply it.
Autogeneration has limits
Autogeneration catches most common changes — new tables, new columns, type changes — by comparing models to the live schema. It doesn’t reliably catch everything: a renamed column looks like “drop one column, add another” rather than a rename, and some changes need to be written or corrected by hand. Reviewing every autogenerated script before applying it is standard practice, not an edge case to worry about occasionally.
What about Django?
If you’re using Django instead of SQLAlchemy, you don’t need Alembic — Django ships its own built-in migration system (makemigrations/migrate) that does the equivalent job for Django’s ORM. Alembic is specifically the answer for the SQLAlchemy ecosystem, covered alongside Django’s own migrations in SQLAlchemy vs Django ORM.
When you actually need it
The moment a SQLAlchemy-backed application has a real database with real data in it, not just a fresh schema you can recreate freely — that’s when hand-editing the schema becomes risky and Alembic’s versioned, reviewable migration history becomes worth the setup.
Frequently Asked Questions
What is Alembic used for?
Managing database schema changes over time for SQLAlchemy projects — generating versioned migration scripts, applying them in order, and rolling them back if needed, instead of hand-editing a production database’s schema directly.
Is Alembic part of SQLAlchemy?
No — it’s a separate but tightly integrated tool built by the same maintainer specifically to handle migrations, which SQLAlchemy itself doesn’t include. It’s the standard pairing for any production SQLAlchemy project.
Does Alembic generate migrations automatically?
It can autogenerate a migration script by comparing your current SQLAlchemy models against the database’s actual schema, though the generated script should always be reviewed — autogeneration catches most common changes but not everything (like renamed columns, which look like a drop-and-add unless you edit the script).
Do you need Alembic if you’re using Django instead of SQLAlchemy?
No — Django ships its own built-in migration system (makemigrations/migrate) that serves the same purpose for Django’s ORM. Alembic is specifically the SQLAlchemy-ecosystem answer to the same problem.