diff --git a/docs/concepts/schema.rst b/docs/concepts/schema.rst new file mode 100644 index 00000000..f10436cb --- /dev/null +++ b/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`. diff --git a/docs/index.rst b/docs/index.rst index 10e95a39..f4e537d6 100644 --- a/docs/index.rst +++ b/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: diff --git a/docs/schemachange.rst b/docs/schemachange.rst new file mode 100644 index 00000000..5d385b7b --- /dev/null +++ b/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