Commit | Line | Data |
---|---|---|
4436fbcd CAW |
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 | ||
e9f33066 CAW |
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 | ||
4436fbcd CAW |
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! |