Migrating the Schema

As development progresses for your custom app, you may need to migrate the database schema from time to time.

See also this general discussion of the Database Schema.

Note

The only “safe” migrations are those which add or modify (or remove) “custom” tables, i.e. those not provided by the rattail.db.model package. This doc assumes you are aware of this and are only attempting a safe migration.

Modify ORM Classes

First step is to modify the ORM classes defined by your app, so they reflect the “desired” schema. Typically this will mean editing files under the poser.db.model package within your source. In particular when adding new tables, you must be sure to include them within poser/db/model/__init__.py.

As noted above, only those classes not provided by rattail.db.model should be modified here, to be safe. If you wish to “extend” an existing table, you must create a secondary table which ties back to the first via one-to-one foreign key relationship.

Create Migration Script

Next you will create the Alembic script which is responsible for performing the schema migration against a database. This is typically done like so:

workon poser
cdvirtualenv
bin/alembic -c app/rattail.conf revision --autogenerate --head poser@head -m "describe migration here"

This will create a new file under e.g. ~/src/poser/poser/db/alembic/versions/. You should edit this file as needed to ensure it performs all steps required for the migration. Technically it should support downgrade as well as upgrade, although in practice that isn’t always required.

Upgrade Database Schema

Once you’re happy with the new script, you can apply it against your dev database with something like:

workon poser
cdvirtualenv
bin/alembic -c app/rattail.conf upgrade heads