Alembic Migrations

bp alembic

Move from SQLALChemy-migrate to Alembic as the tool for maintaining SQL Repos.

Problem Description

The OpenStack community is gradually moving away from using sqlalchemy-migrate in favor of Alembic. In order to allow various projects within the community time to make the switch, OpenStack is maintaining a fork of sqlalchemy-migrate. Keystone needs to follow suit, or we will be using an unsupported tool.

Proposed Change

Continue using sqlalchemy-migrate for the current set of migrations. All new migrations will use Alembic.

Alembic migrations will run after sqlachemy-migrate migrations on upgrade and vice versa on downgrade. oslo.db’s migration_cli utilities will be used.

In two releases, we should be able to collapse the last of the sqlalchemy-migrate based migrations into a base Alembic based migration.

Security Impact


Notifications Impact


Other End User Impact


Performance Impact


Other Deployer Impact


Developer Impact

Existing modules that need migrations will need to create an “alembic” directory along with “migrate_repo”. It can be done using alembic init alembic command in the directory with the module.



Primary assignee:


Other contributors:


Work Items

  • Start using migration_cli from oslo.db with disabled Alembic

  • Create Alembic repos where sqlalchemy-migrate is now used, add a requirement to have Alembic repos if migrations are required and remove a requirement to have a “repo_migrate”.


The feature requires to have a new dependency for Keystone – “Alembic”. Now Alembic is required anyway by oslo.db, which is a requirement for Keystone.

Documentation Impact

  • Describe how to create migrations with Alembic