62ee9e7390
The db.rst file had two top level headings and the second wasn't being rendered in the html pages. Separated the zero downtime section into its own section to fix this and made a few updates to the text. Change-Id: I913326653642d8f19173f18868d4e8cbb89a5b77
5.0 KiB
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>
Note
In the Ocata release (14.0.0), the database migration engine was
changed from SQLAlchemy Migrate to Alembic. This
necessitated some changes in the glance-manage tool. While
the user interface has been kept as similar as possible, the
glance-manage tool included with the Ocata and more recent
releases is incompatible with the "legacy" tool. If you are consulting
these documents for information about the glance-manage
tool in the Newton or earlier releases, please see the legacy-database-management
page.
Migration Scripts
The migration scripts are stored in the directory:
glance/db/sqlalchemy/alembic_migrations/versions
As mentioned above, these scripts utilize the Alembic migration
engine, which was first introduced in the Ocata release. All database
migrations up through the Liberty release are consolidated into one
Alembic migration script named liberty_initial. Mitaka
migrations are retained, but have been rewritten for Alembic and named
using the new naming convention.
A fresh Glance installation will apply the following migrations:
liberty-initialmitaka01mitaka02ocata01
Note
The "old-style" migration scripts have been retained in their current directory in the Ocata release so that interested operators can correlate them with the new migrations. This directory will be removed in future releases.
In particular, the "old-style" script for the Ocata migration, 045_add_visibility.py is retained for operators who are conversant in SQLAlchemy Migrate and are interested in comparing it with a "new-style" Alembic migration script. The Alembic script, which is the one actually used to do the upgrade to Ocata, is ocata01_add_visibility_remove_is_public.py.
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.
Note
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 is 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 is ocata01.
This naming convention will change slightly with the introduction of
zero-downtime upgrades, which is EXPERIMENTAL in Ocata, but is projected
to be the official upgrade method beginning with the Pike release. See
zero-downtime for more
information.
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.
Downgrading an Existing Database
Downgrading an existing database is NOT SUPPORTED.
Upgrades involve complex operations and can fail. Before attempting any upgrade, you should make a full database backup of your production data. As of the OpenStack Kilo release (April 2013), database downgrades are not supported, and the only method available to get back to a prior database version is to restore from backup.