From cca5d508ad4faeacdb0a7bbcb51243bef507090e Mon Sep 17 00:00:00 2001
From: Berker Peksag <berker.peksag@gmail.com>
Date: Thu, 2 Oct 2014 20:17:34 +0300
Subject: [PATCH] Add initial migration guide.

This can be moved to docs/source/devel/migrations.rst.
---
 mediagoblin/db/migrations/README | 58 +++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/mediagoblin/db/migrations/README b/mediagoblin/db/migrations/README
index 98e4f9c4..93d85eff 100644
--- a/mediagoblin/db/migrations/README
+++ b/mediagoblin/db/migrations/README
@@ -1 +1,57 @@
-Generic single-database configuration.
\ No newline at end of file
+Migration Guide
+---------------
+
+Alembic comes with a CLI called ``alembic``.
+
+Create a Migration
+^^^^^^^^^^^^^^^^^^
+
+Lets create our first migration::
+
+    $ alembic revision -m "add favourite_band field"
+      Generating
+      /your/gmg/path/mediagoblin/db/migrations/versions/1e3793de36a_add_favourite_band_field.py ... done
+
+By default, migration files have two methods: ``upgrade`` and ``downgrade``.
+Alembic will invoke these methods to apply the migrations to your current
+database.
+
+Now, we need to edit our newly created migration file
+``1e3793de36a_add_favourite_band_field.py`` to add a new column ``favourite_band``
+to ``core__users`` table::
+
+    def upgrade():
+        op.add_column('core__users', sa.Column('favourite_band', sa.Unicode(100)))
+
+
+    def downgrade():
+        op.drop_column('core__users', 'favourite_band')
+
+.. note::
+
+   Alembic can also generate `automatic migrations <http://alembic.readthedocs.org/en/latest/tutorial.html#auto-generating-migrations>`__.
+
+Then we can run ``gmg dbupdate`` to apply the new migration::
+
+    $ gmg dbupdate
+    INFO  [alembic.migration] Context impl SQLiteImpl.
+    INFO  [alembic.migration] Will assume non-transactional DDL.
+    INFO  [alembic.migration] Running upgrade None -> 1e3793de36a, add favourite band field
+
+If you want to revert that migration, simply run::
+
+    $ alembic downgrade -1
+
+.. warning::
+
+   Currently, Alembic cannot do ``DROP COLUMN``, ``ALTER COLUMN`` etc.
+   operations in SQLite. Please see https://bitbucket.org/zzzeek/alembic/issue/21/column-renames-not-supported-on-sqlite
+   for detailed information.
+
+Glossary
+^^^^^^^^
+
+* ``alembic.ini``: The Alembic configuration file. The ``alembic`` CLI will
+  look that file everytime it invaked.
+* ``mediagoblin/db/migrations/versions/``: Alembic will add new migration files
+  to this directory.
-- 
2.25.1