Add initial migration guide.

This can be moved to docs/source/devel/migrations.rst.

diff --git a/mediagoblin/db/migrations/README b/mediagoblin/db/migrations/README
index 98e4f9c44effe479ed38c66ba922e7bcc672916f..93d85effbbfddfe204b0202c58f41d5107ef5903 100644 (file)
--- 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.