Migrating the Schema
====================

Rattail uses `Alembic`_ to manage its schema migrations.

.. _Alembic: https://alembic.sqlalchemy.org/en/latest/

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:

.. code-block:: sh

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

.. note::
   Since ``alembic`` is not a "native" Rattail command, we cannot use
   :doc:`/base/config/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:

.. code-block:: ini

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

.. code-block:: ini

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

.. code-block:: sh

   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