extension migrations

Allow each of the extensions to have their own
sql migration repository instead of mixing them into
the common repo.  db_sync must be called explicitly on the extension.

In the past, it was assumed that only migrations for backends backed in
sql would be run.  In practice, however, all of the migrations were run
every time.  The code has been modified to reflect this.

Adds parameter --extension to the cli for db_sync and db_version

to test out the migrations

bin/keystone-manage db_sync --extension example

will migrate to version 1 and

bin/keystone-manage db_sync --extension example 0

will migrate it back to 0

to check the version

bin/keystone-manage db_version --extension example

blueprint multiple-sql-migrate-repos

DocImpact

Change-Id: I6852d75bde6506c535fa3d74537e3c1bbd6578d8

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/source/developing.rst b/doc/source/developing.rst
index c14ef7ab..2cf4b98e 100644
--- a/doc/source/developing.rst
+++ b/doc/source/developing.rst
@@ -71,6 +71,36 @@ place::
 
 .. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient
 
+Database Schema Migrations
+--------------------------
+
+Keystone uses SQLAlchemy-migrate
+_`SQLAlchemy-migrate`:http://code.google.com/p/sqlalchemy-migrate/ to migrate the SQL database
+between revisions.  For core components, the migrations are kept in a central
+repository under keystone/common/sql/migrate_repo.
+
+Extensions should be created as directories under `keystone/contrib`.  An
+extension that requires sql migrations should not change the common repository,
+but should instead have its own repository.  This repository must be in the
+extension's directory in `keystone/contrib/<extension>/migrate_repo.`  In
+addition it needs a subdirectory named `versions`.  For example, if the
+extension name is `my_extension` then the directory structure would be
+`keystone/contrib/my_extension/migrate_repo/versions/`.  For the migration
+o work, both the migrate_repo and versions subdirectories must have empty
+__init__.py files.  SQLAlchemy-migrate will look for a configuration file in
+the migrate_repo named migrate.cfg. This conforms to a Key/value ini file
+format.  A sample config file with the minimal set of values is::
+
+    [db_settings]
+    repository_id=my_extension
+    version_table=migrate_version
+    required_dbs=[]
+
+The directory `keystone/contrib/example` contains a sample extension migration.
+
+Migrations for extension must be explicitly run. To run a migration for a specific
+extension, run  `keystone-manage --extension <name> db_sync`.
+
 Initial Sample Data
 -------------------