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

docs/data/db.rst

@@ -1,5 +0,0 @@
-
-Rattail Database
-================
-
-TODO

docs/data/db/extend.rst

@@ -0,0 +1,20 @@
+
+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).
+
+TODO: obviously need to say how one can go about extending schema...

docs/data/db/index.rst

@@ -0,0 +1,12 @@
+
+Rattail Database
+================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview
+   schema
+   extend
+   migrate

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

docs/data/db/overview.rst

@@ -0,0 +1,13 @@
+
+Overview
+========
+
+Rattail comes with its own database, schema for which contains most "common"
+tables needed to support a retail organization, but which may be "extended" as
+needed by an app.
+
+This database, if present, must use the PostgreSQL DB engine.
+
+The database is not strictly required, meaning e.g. the :doc:`/base/index` will
+function without it.  But most advanced features will benefit from having a
+database in place, and many do require it.

docs/data/db/schema.rst

@@ -0,0 +1,18 @@
+
+Core Schema
+===========
+
+Rattail's core database schema contains all tables deemed "generic" enough to
+be potentially useful to "any" retail organization.  Many of the tables may go
+unused by a particular org, but they will all be present, if the DB exists.
+Some of the tables are truly generic, and some may be specific to Rattail
+itself.
+
+Assuming your DB is named "poser" you can see its table list like so:
+
+.. code-block:: sh
+
+   sudo -u postgres psql -c '\d' poser
+
+Note of course that this will show *all* tables in your DB, not just the core
+schema tables.

docs/data/index.rst

@@ -6,7 +6,7 @@ Data Layer
    :maxdepth: 2
    :caption: Contents:
 
-   db
+   db/index
    trainwreck
    other
    importing

docs/data/other.rst

@@ -2,4 +2,33 @@
 POS and Other Data Stores
 =========================
 
-TODO
+Rattail is able to read from and/or write to various other data stores, for
+example:
+
+* POS systems
+* any SQL DB
+* any web API
+* Excel, CSV etc.
+
+When we say that "Rattail is able" to do this, really we mean that all the
+building blocks are there already and implementing specific import/export logic
+should require minimal effort.  In some cases a "common" e.g. POS system may be
+well-supported out of the box.
+
+Supported POS Systems
+---------------------
+
+The following POS systems are considered well-supported.  Integration packages
+for each are continually being developed.  However the nature of integrations
+possible with each of these will vary:
+
+* CORE-POS
+* ECRS Catapult
+* LOC SMS
+
+These systems are not well-supported but have received some amount of attention
+in the past, so are not entirely unknown:
+
+* CAM32
+* Revel
+* ScanMaster