Migrating the Schema

Rattail uses Alembic to manage its schema migrations.

Schema is defined in the model module(s) using SQLAlchemy, but the logic for actually installing the schema is stored as Alembic “version” scripts.

Assuming a typical setup, you can migrate your DB to the latest schema like so:

cd /srv/envs/poser
bin/alembic -c app/rattail.conf upgrade heads

Note

Since alembic is not a “native” Rattail command, we cannot use Config File Inheritance. In practice this means you probably cannot use your quiet.conf file here. This is because Alembic will simply read the specified file for its config, and will not know to auto-include any others. Therefore the config file you specify, must itself contain the [alembic] section; examples shown below.

Note that this will migrate both the core Rattail schema, as well as any extensions you’ve defined. Or rather, it will migrate according to what it finds in the config file.

A typical config snippet with just the core Rattail schema:

[alembic]
script_location = rattail.db:alembic
version_locations = rattail.db:alembic/versions

A typical config snippet for a project which extends schema and includes some schema extensions which are provided by the rattail-corepos integration package:

[alembic]
script_location = poser.db:alembic
version_locations = poser.db:alembic/versions rattail_corepos.db:alembic/versions rattail.db:alembic/versions

Caution

The order does matter within the version_locations setting above. It should progress from “custom” to “core” when reading left to right.

Since we’re using Alembic here, we have other commands available to us for viewing the overall migration history etc. For instance:

cd /srv/envs/poser
bin/alembic -c app/rattail.conf heads
bin/alembic -c app/rattail.conf current
bin/alembic -c app/rattail.conf history