.. highlight:: sh

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
---------------------

(For more authoritative docs see :ref:`alembic:multiple_bases`.)

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.

.. code-block:: ini

   [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.  Please pay close attention and
make sure you have all args correct::

   cd /srv/envs/poser
   bin/alembic -c app/rattail.conf revision --autogenerate --head base --branch-label=poser --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.

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