mediagoblin/db/migrations/README

   1 Migration Guide
   2 ---------------
   3
   4 Alembic comes with a CLI called ``alembic``.
   5
   6 Create a Migration
   7 ^^^^^^^^^^^^^^^^^^
   8
   9 Lets create our first migration::
  10
  11     $ alembic revision -m "add favourite_band field"
  12       Generating
  13       /your/gmg/path/mediagoblin/db/migrations/versions/1e3793de36a_add_favourite_band_field.py ... done
  14
  15 By default, migration files have two methods: ``upgrade`` and ``downgrade``.
  16 Alembic will invoke these methods to apply the migrations to your current
  17 database.
  18
  19 Now, we need to edit our newly created migration file
  20 ``1e3793de36a_add_favourite_band_field.py`` to add a new column ``favourite_band``
  21 to ``core__users`` table::
  22
  23     def upgrade():
  24         op.add_column('core__users', sa.Column('favourite_band', sa.Unicode(100)))
  25
  26
  27     def downgrade():
  28         op.drop_column('core__users', 'favourite_band')
  29
  30 .. note::
  31
  32    Alembic can also generate `automatic migrations <http://alembic.readthedocs.org/en/latest/tutorial.html#auto-generating-migrations>`__.
  33
  34 Then we can run ``gmg dbupdate`` to apply the new migration::
  35
  36     $ gmg dbupdate
  37     INFO  [alembic.migration] Context impl SQLiteImpl.
  38     INFO  [alembic.migration] Will assume non-transactional DDL.
  39     INFO  [alembic.migration] Running upgrade None -> 1e3793de36a, add favourite band field
  40
  41 If you want to revert that migration, simply run::
  42
  43     $ alembic downgrade -1
  44
  45 .. warning::
  46
  47    Currently, Alembic cannot do ``DROP COLUMN``, ``ALTER COLUMN`` etc.
  48    operations in SQLite. Please see https://bitbucket.org/zzzeek/alembic/issue/21/column-renames-not-supported-on-sqlite
  49    for detailed information.
  50
  51 Glossary
  52 ^^^^^^^^
  53
  54 * ``alembic.ini``: The Alembic configuration file. The ``alembic`` CLI will
  55   look that file everytime it invaked.
  56 * ``mediagoblin/db/migrations/versions/``: Alembic will add new migration files
  57   to this directory.