Add first docs for Rattail DB, and POS / other data stores

docs/data/db/migrate.rst

@@ -0,0 +1,62 @@
+
+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