From f399e3be550024ea7aa0ac747a00b71f4bbbfc6e Mon Sep 17 00:00:00 2001
From: Nikolay Mahotkin <nmakhotkin@mirantis.com>
Date: Tue, 5 May 2015 14:41:25 +0300
Subject: [PATCH] Adding migrations README

 * Simple info about migrations in main README.rst also

Change-Id: I0ab109471d9b36dcedc58bdef471ef9acf5898f3
---
 README.rst                                    | 13 +++-
 .../migration/alembic_migrations/README       |  1 -
 .../migration/alembic_migrations/README.md    | 66 +++++++++++++++++++
 3 files changed, 78 insertions(+), 2 deletions(-)
 delete mode 100644 mistral/db/sqlalchemy/migration/alembic_migrations/README
 create mode 100644 mistral/db/sqlalchemy/migration/alembic_migrations/README.md

diff --git a/README.rst b/README.rst
index a6acf426..5cc60655 100644
--- a/README.rst
+++ b/README.rst
@@ -120,8 +120,19 @@ Before starting Mistral server, run sync_db script. It prepares the DB, creates
 
     python tools/sync_db.py --config-file path_to_config*
 
-*Note: After local installation you will see **mistral-server** command in your environment*.
+*Note: After local installation you will see **mistral-server** and **mistral-db-manage** commands in your environment*.
 
+Migrations
+----------
+
+*mistral-db-manage* command can be used for migrations. If Mistral is not installed in system then this script can be
+ found at *mistral/db/sqlalchemy/migration/cli.py*, it can be executed using Python.
+
+For updating the database to the latest revision type::
+
+    mistral-db-manage --config-file <path-to-mistral.conf> upgrade head
+
+For more detailed information about *mistral-db-manage* script please see migration readme here - https://github.com/stackforge/mistral/blob/master/mistral/db/sqlalchemy/migration/alembic_migrations/README.md
 
 Running Mistral API server
 --------------------------
diff --git a/mistral/db/sqlalchemy/migration/alembic_migrations/README b/mistral/db/sqlalchemy/migration/alembic_migrations/README
deleted file mode 100644
index 98e4f9c4..00000000
--- a/mistral/db/sqlalchemy/migration/alembic_migrations/README
+++ /dev/null
@@ -1 +0,0 @@
-Generic single-database configuration.
\ No newline at end of file
diff --git a/mistral/db/sqlalchemy/migration/alembic_migrations/README.md b/mistral/db/sqlalchemy/migration/alembic_migrations/README.md
new file mode 100644
index 00000000..abb22a31
--- /dev/null
+++ b/mistral/db/sqlalchemy/migration/alembic_migrations/README.md
@@ -0,0 +1,66 @@
+The migrations in `alembic_migrations/versions` contain the changes needed to migrate
+between Mistral database revisions. A migration occurs by executing a script that
+details the changes needed to upgrade the database. The migration scripts
+are ordered so that multiple scripts can run sequentially. The scripts are executed by
+Mistral's migration wrapper which uses the Alembic library to manage the migration. Mistral
+supports migration from Kilo or later.
+
+You can upgrade to the latest database version via:
+```
+mistral-db-manage --config-file /path/to/mistral.conf upgrade head
+```
+
+You can populate the database with standard actions and workflows:
+```
+mistral-db-manage --config-file /path/to/mistral.conf populate
+```
+
+To check the current database version:
+```
+mistral-db-manage --config-file /path/to/mistral.conf current
+```
+
+To create a script to run the migration offline:
+```
+mistral-db-manage --config-file /path/to/mistral.conf upgrade head --sql
+```
+
+To run the offline migration between specific migration versions:
+```
+mistral-db-manage --config-file /path/to/mistral.conf upgrade <start version>:<end version> --sql
+```
+
+Upgrade the database incrementally:
+```
+mistral-db-manage --config-file /path/to/mistral.conf upgrade --delta <# of revs>
+```
+
+Or, upgrade the database to one newer revision:
+```
+mistral-db-manage --config-file /path/to/mistral.conf upgrade +1
+```
+
+Create new revision:
+```
+mistral-db-manage --config-file /path/to/mistral.conf revision -m "description of revision" --autogenerate
+```
+
+Create a blank file:
+```
+mistral-db-manage --config-file /path/to/mistral.conf revision -m "description of revision"
+```
+
+This command does not perform any migrations, it only sets the revision.
+Revision may be any existing revision. Use this command carefully.
+```
+mistral-db-manage --config-file /path/to/mistral.conf stamp <revision>
+```
+
+To verify that the timeline does branch, you can run this command:
+```
+mistral-db-manage --config-file /path/to/mistral.conf check_migration
+```
+
+If the migration path has branch, you can find the branch point via:
+```
+mistral-db-manage --config-file /path/to/mistral.conf history
\ No newline at end of file