diff options
| -rw-r--r-- | mediagoblin/db/migrations/README | 58 |
1 files changed, 57 insertions, 1 deletions
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. |