openstack
/
keystone
Code Issues Proposed changes

Revised schema migration docs 

Change-Id: I484964d1012163922d619ae3a7a66ea3d07d6b19
This commit is contained in:
Dolph Mathews 2011-11-30 11:06:44 -06:00
parent 1778dcf006
commit cb2da13571
2 changed files with 29 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/source/migration.rst
View File

@ -1,36 +1,37 @@
================
Using Migrations
================
===================
Database Migrations
===================
Keystone uses sqlalchemy-migrate to manage migrations.
Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage migrations.
.. WARNING::
Running Migrations
======================
Backup your database before applying migrations. Migrations may attempt to modify both your schema and data, and could result in data loss.
Keep backups of your db. Migrations will modify data and schema. If they fail, you could lose data.
Always review the behavior of migrations in a staging environment before applying them in production.
Getting Started
===============
Add your existing database to version control. ::
Migrations are tracked using a metadata table. Place an existing database under version control to enable migration support (SQLite in this case)::
$python keystone/backends/sqlalchemy/migrate_repo/manage.py version_control --url=sqlite:///bin/keystone.db --repository=keystone/backends/sqlalchemy/migrate_repo/
$ python keystone/backends/sqlalchemy/migrate_repo/manage.py version_control --url=sqlite:///bin/keystone.db --repository=keystone/backends/sqlalchemy/migrate_repo/
You can set your database to the current schema version number using a
SQL command. For example, to set your current db version to version number 1,
which maps to diablo release, make this call::
If you are starting with an existing schema, you can set your database to the current schema version number using a
SQL command. For example, if you're starting from a
diablo-compatible database, set your current database version to ``1``::
UPDATE migrate_version SET version=1;
Perform Upgrades/Downgrades
Upgrading & Downgrading
=======================
Example Upgrade::
Fresh installs of Keystone will need to run database upgrades, which will build a schema and bootstrap it with any necessary data.
$python keystone/backends/sqlalchemy/migrate_repo/manage.py upgrade --url=sqlite:///bin/keystone.db --repository=keystone/backends/sqlalchemy/migrate_repo/
Upgrade::
Example Downgrade::
$ python keystone/backends/sqlalchemy/migrate_repo/manage.py upgrade --url=sqlite:///bin/keystone.db --repository=keystone/backends/sqlalchemy/migrate_repo/
$python keystone/backends/sqlalchemy/migrate_repo/manage.py downgrade 1 --url=sqlite:///bin/keystone.db --repository=keystone/backends/sqlalchemy/migrate_repo/
Downgrade (will likely result in data loss!)::
If you get an error that says: migrate.exceptions.DatabaseNotControlledError: migrate_version
that means your database is not versioned controlled. See 'Add your existing database to version control' above.
$ python keystone/backends/sqlalchemy/migrate_repo/manage.py downgrade 1 --url=sqlite:///bin/keystone.db --repository=keystone/backends/sqlalchemy/migrate_repo/

28
doc/source/testing.rst
View File

@ -20,32 +20,20 @@ and aborts after the first test failure (a fail-fast behavior)::
$ ./run_tests.sh
Schema Migration Tests
======================
Testing Schema Migrations
=========================
Schema migrations are tested using SQLAlchemy Migrate's built-in test
runner::
The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time.
The test does not start testing from the very top. In order for the test to run, the database
that is used to test, should be up to version above the version brought forward by the latest script.::
.. WARNING::
This command would create the test db with a version of 0.::
This may leave your database in an inconsistent state; attempt this in non-production environments only!
$python keystone/backends/sqlalchemy/migrate_repo/manage.py version_control sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/
This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control::
Use this command to move to the version that is before our latest script.
$ python keystone/backends/sqlalchemy/migrate_repo/manage.py test --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/
i.e. if our latest script has version 3, we should move to 2.::
$python keystone/backends/sqlalchemy/migrate_repo/manage.py upgrade version_number --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/
Now try::
$python keystone/backends/sqlalchemy/migrate_repo/manage.py test --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/
This tests both forward and backward migrations, and should leave behind
an test sqlite database (``test.db``) that can be safely
removed or simply ignored.
This command refers to a SQLite database used for testing purposes. Depending on the migration, this command alone does not make assertions as to the integrity of your data during migration.
Writing Tests
=============