Add basic schema docs

docs/concepts/schema.rst

@@ -0,0 +1,45 @@
+
+Database Schema
+===============
+
+.. contents:: :local:
+
+Rattail provides a "core" schema which is assumed to be the foundation of any
+Poser app database.
+
+
+Core Tables
+-----------
+
+All tables which are considered part of the Rattail "core" schema, are defined
+as ORM classes within the ``rattail.db.model`` package.
+
+.. note::
+
+   The Rattail project has its roots in retail grocery-type stores, and its
+   schema reflects that to a large degree.  In practice however the software
+   may be used to support a wide variety of apps.  The next section describes
+   that a bit more.
+
+
+Customizing the Schema
+----------------------
+
+Almost certainly a custom app will need some of the core tables, but just as
+certainly, it will *not* need others.  And to make things even more
+interesting, it may need some tables but also need to "supplement" them
+somehow, to track additional data for each record etc.
+
+Any table in the core schema which is *not* needed, may simply be ignored,
+i.e. hidden from the app UI etc.
+
+Any table which is "missing" from core schema, from the custom app's
+perspective, should be added as a custom table.
+
+Also, any table which is "present but missing columns" from the app's
+perspective, will require a custom table.  In this case each record in the
+custom table will "tie back to" the core table record.  The custom record will
+then supply any additional data for the core record.
+
+Defining custom tables, and associated tasks, are documented in
+:doc:`../schemachange`.

docs/index.rst

@@ -12,7 +12,7 @@ attention thus far.
 
 .. _website: https://rattailproject.org/
 
-Getting Started (with Custom Apps):
+Quick Start for Custom Apps:
 
 .. toctree::
    :maxdepth: 1
@@ -20,6 +20,13 @@ Getting Started (with Custom Apps):
    structure
    devenv
    newproject
+   schemachange
+
+Concept Guide:
+
+.. toctree::
+
+   concepts/schema
 
 Narrative Documentation:
 

docs/schemachange.rst

@@ -0,0 +1,63 @@
+
+Migrating the Schema
+====================
+
+.. contents:: :local:
+
+As development progresses for your custom app, you may need to migrate the
+database schema from time to time.
+
+See also this general discussion of the :doc:`concepts/schema`.
+
+.. note::
+
+   The only "safe" migrations are those which add or modify (or remove)
+   "custom" tables, i.e. those *not* provided by the ``rattail.db.model``
+   package.  This doc assumes you are aware of this and are only attempting a
+   safe migration.
+
+
+Modify ORM Classes
+------------------
+
+First step is to modify the ORM classes defined by your app, so they reflect
+the "desired" schema.  Typically this will mean editing files under the
+``poser.db.model`` package within your source.  In particular when adding new
+tables, you must be sure to include them within ``poser/db/model/__init__.py``.
+
+As noted above, only those classes *not* provided by ``rattail.db.model``
+should be modified here, to be safe.  If you wish to "extend" an existing
+table, you must create a secondary table which ties back to the first via
+one-to-one foreign key relationship.
+
+
+Create Migration Script
+-----------------------
+
+Next you will create the Alembic script which is responsible for performing the
+schema migration against a database.  This is typically done like so:
+
+.. code-block:: sh
+
+   workon poser
+   cdvirtualenv
+   bin/alembic -c app/rattail.conf revision --autogenerate --head poser@head -m "describe migration here"
+
+This will create a new file under
+e.g. ``~/src/poser/poser/db/alembic/versions/``.  You should edit this file as
+needed to ensure it performs all steps required for the migration.  Technically
+it should support downgrade as well as upgrade, although in practice that isn't
+always required.
+
+
+Upgrade Database Schema
+-----------------------
+
+Once you're happy with the new script, you can apply it against your dev
+database with something like:
+
+.. code-block:: sh
+
+   workon poser
+   cdvirtualenv
+   bin/alembic -c app/rattail.conf upgrade heads