Extending the Schema

While the core Rattail schema provides “most” tables you may need, it is quite common for an app to need yet more tables to satisfy its features.

Extending the schema really just means, you can add extra tables as needed, and modify the schema for each of those going forward. The core tables provided by Rattail schema should never be directly modified, but your extra tables are fair game.

It is important that you name all extra tables with a prefix unique to your app, e.g. poser_product for a product extension table, or poser_widget for a totally custom table. Avoid prefix-less names like widget because Rattail reserves the prefix-less namespace for its core schema. Also, certain integration packages reserve other namespaces (e.g. corepos_ prefix is used by the rattail-corepos package for extension tables it provides).

First Alembic Version

In order to add custom extensions to the schema, you will need to establish some things for sake of Alembic. Note that these steps are only required for the “first” extension you add; subsequent versions are somewhat simpler and are covered in the next section.

First you should have the basic folder structure:

cd ~/src/poser
mkdir -p poser/db/alembic/versions

You must edit your config file at /srv/envs/poser/app/rattail.conf and update the version_locations setting for Alembic, to include your new folder. Note the way we specify the path below; this ensures it works no matter where things actually live on disk. Also note that we specify the custom location first, core rattail goes last.

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

Run a command like this (replacing names etc. as needed) to generate the script in your versions folder:

cd /srv/envs/poser
bin/alembic -c app/rattail.conf revision --autogenerate --head rattail@head --version-path ~/src/poser/poser/db/alembic/versions/ -m 'initial Poser tables'

If all goes well that command output should end by telling you where the new script lives. You will want to review this of course, to make sure it includes all your new tables.

But you must also declare this version as a new branch head. This lets your custom versions have a life of their own, essentially. So going forward, when you upgrade your DB schema, both the core Rattail tables, as well as your own, will be migrated properly.

There are two variables near the top of the script which you must edit, like so:

down_revision = None
branch_labels = ('poser',)

And with all that in place, you can apply the migration to your DB (this part is normal):

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

Additional Alembic Versions

TODO