-- How to write migrations? Maybe there will be a tutorial here in the
- future... in the meanwhile, look at existing migrations in
- `mediagoblin/db/migrations.py` and look in
- `mediagoblin/tests/test_sql_migrations.py` for examples.
-- Common pattern: use `inspect_table` to get the current state
- of the table before we run alterations on it.
-- Make sure you set the RegisterMigration to be the next migration in
- order.
-- What happens if you're adding a *totally new* table? In this case,
- you should copy the table in entirety as it exists into
- migrations.py then create the tables based off of that... see
- add_collection_tables. This is easier than reproducing the SQL by
- hand.
-- If you're writing a feature branch, you don't need to keep adding
- migrations every time you change things around if your database
- structure is in flux. Just alter your migrations so that they're
- correct for the merge into master.
+ Anyway, Alembic has its own conventions for migrations; follow those.
+- Alembic's documentation is pretty good; you don't need to worry about
+ setting up the migration environment or the config file so you can
+ skip those parts. You can start at the
+ `Create a Migration Script <http://alembic.readthedocs.org/en/latest/tutorial.html#create-a-migration-script>`_
+ section.
+- *Users* should only use `./bin/gmg dbupdate`. However, *developers*
+ may wish to use the `./bin/gmg alembic` subcommand, which wraps
+ alembic's own command line interface. Alembic has some tools for
+ `autogenerating migrations <http://alembic.readthedocs.org/en/latest/autogenerate.html>`_,
+ and they aren't perfect, but they are helpful. (You can pass in
+ `./bin/gmg alembic --with-plugins revision --autogenerate` if you need
+ to include plugins in the generated output; see the
+ :ref:`plugin database chapter <plugin-database-chapter>` for more info.)