diff --git a/docs/data/db.rst b/docs/data/db.rst deleted file mode 100644 index 5d712e6..0000000 --- a/docs/data/db.rst +++ /dev/null @@ -1,5 +0,0 @@ - -Rattail Database -================ - -TODO diff --git a/docs/data/db/extend.rst b/docs/data/db/extend.rst new file mode 100644 index 0000000..42f1a3d --- /dev/null +++ b/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... diff --git a/docs/data/db/index.rst b/docs/data/db/index.rst new file mode 100644 index 0000000..9ef7701 --- /dev/null +++ b/docs/data/db/index.rst @@ -0,0 +1,12 @@ + +Rattail Database +================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + schema + extend + migrate diff --git a/docs/data/db/migrate.rst b/docs/data/db/migrate.rst new file mode 100644 index 0000000..84e73c7 --- /dev/null +++ b/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 diff --git a/docs/data/db/overview.rst b/docs/data/db/overview.rst new file mode 100644 index 0000000..4071e8f --- /dev/null +++ b/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. diff --git a/docs/data/db/schema.rst b/docs/data/db/schema.rst new file mode 100644 index 0000000..01d6169 --- /dev/null +++ b/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. diff --git a/docs/data/index.rst b/docs/data/index.rst index b37cda0..adfa00e 100644 --- a/docs/data/index.rst +++ b/docs/data/index.rst @@ -6,7 +6,7 @@ Data Layer :maxdepth: 2 :caption: Contents: - db + db/index trainwreck other importing diff --git a/docs/data/other.rst b/docs/data/other.rst index 3e948a5..7b92068 100644 --- a/docs/data/other.rst +++ b/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