Database Management

The default metadata driver for Glance uses sqlalchemy, which implies there exists a backend database which must be managed. The glance-manage binary provides a set of commands for making this easier.

The commands should be executed as a subcommand of ‘db’:

glance-manage db <cmd> <args>

Sync the Database

glance-manage db sync [VERSION]

Place an existing database under migration control and upgrade it to the specified VERSION or to the latest migration level if VERSION is not specified.


Prior to Ocata release the database version was a numeric value. For example: for the Newton release, the latest migration level was 44. Starting with Ocata, database version will be a revision name corresponding to the latest migration included in the release. For the Ocata release, there is only one database migration and it is identified by revision ocata01. So, the database version for Ocata release would be ocata01.

However, with the introduction of zero-downtime upgrades, database version will be a composite version including both expand and contract revisions. To achieve zero-downtime upgrades, we split the ocata01 migration into ocata_expand01 and ocata_contract01. During the upgrade process, the database would initially be marked with ocata_expand01 and eventually after completing the full upgrade process, the database will be marked with ocata_contract01. So, instead of one database version, an operator will see a composite database version that will have both expand and contract versions. A database will be considered at Ocata version only when both expand and contract revisions are at the latest revisions possible. For a successful Ocata rolling upgrade, the database should be marked with both ocata_expand01, ocata_contract01.

Determining the Database Version

glance-manage db version

This will print the current migration level of a Glance database.

Upgrading an Existing Database

glance-manage db upgrade [VERSION]

This will take an existing database and upgrade it to the specified VERSION.

Expanding the Database

glance-manage db expand

This will run the expansion phase of a rolling upgrade process. Database expansion should be run as the first step in the rolling upgrade process before any new services are started.

Migrating the Data

glance-manage db migrate

This will run the data migrate phase of a rolling upgrade process. Database migration should be run after database expansion and before database contraction has been performed.

Contracting the Database

glance-manage db contract

This will run the contraction phase of a rolling upgrade process. Database contraction should be run as the last step of the rolling upgrade process after all old services are upgraded to new ones.

Downgrading an Existing Database

Upgrades involve complex operations and can fail. Before attempting any upgrade, you should make a full database backup of your production data. As of Kilo, database downgrades are not supported, and the only method available to get back to a prior database version is to restore from backup[1].