Revised schema migration docs

Change-Id: I484964d1012163922d619ae3a7a66ea3d07d6b19

2 files changed, 29 insertions, 40 deletions

diff --git a/doc/source/migration.rst b/doc/source/migration.rst
index 6bd25fdc..2131178a 100644
--- a/doc/source/migration.rst
+++ b/doc/source/migration.rst
@@ -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/
diff --git a/doc/source/testing.rst b/doc/source/testing.rst
index effb730d..82a33604 100644
--- a/doc/source/testing.rst
+++ b/doc/source/testing.rst
@@ -20,32 +20,20 @@ and aborts after the first test failure (a fail-fast behavior)::
 
     $ ./run_tests.sh
 
-Schema Migration Tests
-======================
-
-Schema migrations are tested using SQLAlchemy Migrate's built-in test
-runner::
-
-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.::
-
-This command would create the test db with a version of 0.::
-
-$python keystone/backends/sqlalchemy/migrate_repo/manage.py version_control sqlite:///test.db   --repository=keystone/backends/sqlalchemy/migrate_repo/
+Testing Schema Migrations
+=========================
 
-Use this command to move to the version that is before our latest script.
+The application of schema migrations can be tested using SQLAlchemy Migrate’s built-in test runner, one migration at a time.
 
-i.e. if our latest script has version 3, we should move to 2.::
+.. WARNING::
 
-$python keystone/backends/sqlalchemy/migrate_repo/manage.py upgrade version_number --url=sqlite:///test.db   --repository=keystone/backends/sqlalchemy/migrate_repo/
+    This may leave your database in an inconsistent state; attempt this in non-production environments only!
 
-Now try::
+This is useful for testing the *next* migration in sequence (both forward & backward) in a database under version control::
 
-$python keystone/backends/sqlalchemy/migrate_repo/manage.py test  --url=sqlite:///test.db --repository=keystone/backends/sqlalchemy/migrate_repo/
+    $ 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
 =============