docs/source/devel/migrations.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012 by MediaGoblin contributors
   4
   5    To the extent possible under law, the author(s) have dedicated all
   6    copyright and related and neighboring rights to this software to
   7    the public domain worldwide. This software is distributed without
   8    any warranty.
   9
  10    You should have received a copy of the CC0 Public Domain
  11    Dedication along with this software. If not, see
  12    <http://creativecommons.org/publicdomain/zero/1.0/>.
  13
  14 ==========
  15 Migrations
  16 ==========
  17
  18 So, about migrations.  Every time we change the way the database
  19 structure works, we need to add a migration so that people running
  20 older codebases can have their databases updated to the new structure
  21 when they run `./bin/gmg dbupdate`.
  22
  23 The first time `./bin/gmg dbupdate` is run by a user, it creates the
  24 tables at the current state that they're defined in models.py and sets
  25 the migration number to the current migration... after all, migrations
  26 only exist to get things to the current state of the db.  After that,
  27 every migration is run with dbupdate.
  28
  29 There's a few things you need to know:
  30
  31 - We use `Alembic <https://bitbucket.org/zzzeek/alembic>`_ to run
  32   migrations.  We also make heavy use of the
  33   `branching model <http://alembic.readthedocs.org/en/latest/branches.html>`_
  34   for our plugins.  Every plugin gets its own migration branch.
  35 - We used to use `sqlalchemy-migrate
  36   <http://code.google.com/p/sqlalchemy-migrate/>`_.
  37   See `their docs <https://sqlalchemy-migrate.readthedocs.org/>`_.
  38   sqlalchemy-migrate is now only kept around for legacy migrations;
  39   don't add any more!  But some users are still using older databases,
  40   and we need to provide the intermediary "old" migrations for a while.
  41 - SQLAlchemy has two parts to it, the ORM and the "core" interface.
  42   We DO NOT use the ORM when running migrations.  Think about it: the
  43   ORM is set up with an expectation that the models already reflect a
  44   certain pattern.  But if a person is moving from their old pattern
  45   and are running tools to *get to* the current pattern, of course
  46   their current database structure doesn't match the state of the ORM!
  47   Anyway, Alembic has its own conventions for migrations; follow those.
  48 - Alembic's documentation is pretty good; you don't need to worry about
  49   setting up the migration environment or the config file so you can
  50   skip those parts.  You can start at the
  51   `Create a Migration Script <http://alembic.readthedocs.org/en/latest/tutorial.html#create-a-migration-script>`_
  52   section.
  53 - *Users* should only use `./bin/gmg dbupdate`.  However, *developers*
  54   may wish to use the `./bin/gmg alembic` subcommand, which wraps
  55   alembic's own command line interface.  Alembic has some tools for
  56   `autogenerating migrations <http://alembic.readthedocs.org/en/latest/autogenerate.html>`_,
  57   and they aren't perfect, but they are helpful.  (You can pass in
  58   `./bin/gmg alembic --with-plugins revision --autogenerate` if you need
  59   to include plugins in the generated output; see the
  60   :ref:`plugin database chapter <plugin-database-chapter>` for more info.)
  61
  62 That's it for now!  Good luck!