biblioteca/mediagoblin/db/migrations

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 `__.

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.