Alembic
By the SQLAlchemy project
Alembic is a lightweight database migration tool for Python, built by the creator of SQLAlchemy, that generates and applies versioned schema change scripts written in Python.
Definition
Alembic is a lightweight database migration tool for Python, built by the creator of SQLAlchemy, that generates and applies versioned schema change scripts written in Python.
Overview
Alembic is the de facto standard migration tool for Python projects that use SQLAlchemy as their ORM or core SQL toolkit. A migration in Alembic is a Python script with `upgrade()` and `downgrade()` functions, chained together into a linear (or branching) history via revision IDs, so the current schema state can always be derived by replaying the chain from the base revision. Alembic's signature feature is autogeneration: it can compare SQLAlchemy model metadata against the live database schema and produce a draft migration script capturing the difference — new tables, added columns, changed types — which a developer then reviews and edits before committing. This tightens the loop between changing a Python model class and producing the corresponding database indexing or column-level DDL needed in production. Because migrations are plain Python, they can contain arbitrary logic — data backfills, conditional branching per database dialect, or calls into application code — which gives Alembic more flexibility than purely declarative tools, at the cost of needing more care to keep migrations deterministic and idempotent. It is commonly used in Django-adjacent or FastAPI/Flask projects that choose SQLAlchemy over Django's built-in ORM, and pairs naturally with courses like Python for AI & ML where data-layer changes accompany model iteration. Alembic supports the same broad set of databases SQLAlchemy supports, including PostgreSQL, MySQL, and SQLite, and integrates with `alembic upgrade head` / `alembic downgrade -1` commands that are typically wired into deployment scripts or CI jobs.
Key Features
- Migrations written as Python scripts with upgrade() and downgrade() functions
- Autogeneration that diffs SQLAlchemy models against the live database schema
- Linear or branching revision history addressed by revision IDs
- CLI commands (upgrade, downgrade, history, current) for managing migration state
- Support for offline mode, generating SQL scripts without a live connection
- Environment-specific configuration via alembic.ini and env.py
- Works with any database dialect SQLAlchemy supports