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 `sqlalchemy-migrate
  32   <http://code.google.com/p/sqlalchemy-migrate/>`_.
  33   See `their docs <https://sqlalchemy-migrate.readthedocs.org/>`_.
  34 - `Alembic <https://bitbucket.org/zzzeek/alembic>`_ might be a better
  35   choice than sqlalchemy-migrate now or in the future, but we
  36   originally decided not to use it because it didn't have sqlite
  37   support.  It's not clear if that's changed.
  38 - SQLAlchemy has two parts to it, the ORM and the "core" interface.
  39   We DO NOT use the ORM when running migrations.  Think about it: the
  40   ORM is set up with an expectation that the models already reflect a
  41   certain pattern.  But if a person is moving from their old patern
  42   and are running tools to *get to* the current pattern, of course
  43   their current database structure doesn't match the state of the ORM!
  44 - How to write migrations?  Maybe there will be a tutorial here in the
  45   future... in the meanwhile, look at existing migrations in
  46   `mediagoblin/db/migrations.py` and look in
  47   `mediagoblin/tests/test_sql_migrations.py` for examples.
  48 - Common pattern: use `inspect_table` to get the current state
  49   of the table before we run alterations on it.
  50 - Make sure you set the RegisterMigration to be the next migration in
  51   order.
  52 - What happens if you're adding a *totally new* table?  In this case,
  53   you should copy the table in entirety as it exists into
  54   migrations.py then create the tables based off of that... see
  55   add_collection_tables.  This is easier than reproducing the SQL by
  56   hand.
  57 - If you're writing a feature branch, you don't need to keep adding
  58   migrations every time you change things around if your database
  59   structure is in flux.  Just alter your migrations so that they're
  60   correct for the merge into master.
  61
  62 That's it for now!  Good luck!