alembic

Initialize Alembic in a project

$ alembic init [alembic]

$ alembic revision -m "[Add users table]"

$ alembic revision --autogenerate -m "[Add email column]"

$ alembic upgrade head

$ alembic upgrade [revision_id]

$ alembic downgrade -1

$ alembic current

$ alembic history

alembic [options] command [commandoptions_]

Alembic is a database migration tool for SQLAlchemy, Python's popular ORM. It manages incremental, reversible changes to database schemas through version-controlled migration scripts.
Migrations are Python files stored in a versions directory. Each migration has an upgrade() function to apply changes and a downgrade() function to reverse them. Alembic tracks the current database state in a special table, allowing it to determine which migrations need to run.
The --autogenerate feature compares SQLAlchemy model definitions against the current database schema to automatically generate migration scripts. While convenient, generated migrations should be reviewed as autogenerate cannot detect all types of changes.
Configuration is stored in alembic.ini, which specifies the database URL, migration script location, and other settings. The env.py script in the alembic directory handles migration environment setup and can be customized for complex scenarios.

init directory

Initialize a new Alembic environment in the specified directory.

Create a new migration revision file.

Upgrade database to a target revision (use 'head' for latest).

Downgrade database to a target revision (use '-1' for one step back).

Show the current revision of the database.

List revision history.

Show all current head revisions.

Show all branch points.

Set the revision table to a specific version without running migrations.

Display details of a specific revision.

Merge multiple branch heads into one.

Path to alembic.ini configuration file.

Name of config section to use.

Pass additional arguments to env.py.

Auto-generate migration by comparing models to database.

Output SQL instead of applying migrations.

Autogenerate cannot detect all changes (table renames, column type changes on some databases, constraint name changes). Always review generated migrations. Downgrade functions must be manually written or verified for autogenerated migrations. Database URL in alembic.ini may contain credentials that should not be committed.

Alembic was created by Mike Bayer, the author of SQLAlchemy, with the first release in 2011. It was designed to provide a migration solution that integrates naturally with SQLAlchemy's metadata and model system. The name comes from the alchemical vessel used for distillation, fitting the SQLAlchemy naming theme.

flask-migrate(1), django-admin(1), sqlalchemy(1), psql(1)