Add most of the structure! plus several Base Layer docs

docs/base/config/db.rst

@@ -0,0 +1,86 @@
+
+.. highlight:: ini
+
+Storing Config in DB
+====================
+
+We're getting ahead of ourselves a little here, if you're reading this manual
+straight through.  But for reference sake this probably belongs here.
+
+Settings Table
+--------------
+
+If you already have a Rattail DB, then it has a table named ``setting`` which
+is designed to store config values.  It's just a regular table so you can write
+settings via SQL if you like:
+
+.. code-block:: sql
+
+   insert into setting (name, value) values ('rattail.app_title', 'Poser');
+
+   update setting set value = 'Something Else' where name = 'rattail.app_title';
+
+Although the main reason for putting settings in the DB is usually so you can
+edit them via the web app.
+
+
+Telling App to Read Config from DB
+----------------------------------
+
+Well first of all we must assume that the DB connection itself is configured.
+More on that later but let's say you have this in place::
+
+   [rattail.db]
+   default.url = postgresql://user:password@localhost/poser
+
+Then you also must tell the Rattail config engine that a) it should read config
+values from the DB at all, but probably also b) it should *prefer* values from
+the DB over what was read from file.  Do this within your config file::
+
+   [rattail.config]
+   usedb = true
+   preferdb = true
+
+With this in place, when the app requests a config value, it will come from the
+DB if present, falling back to the file value if that exists.
+
+
+File vs. DB Setting Names
+-------------------------
+
+You may have noticed that the SQL examples above, and the examples used in
+:doc:`syntax` are really for the same 'app_title' setting, but there is a key
+difference in naming.
+
+So in a config file you might have this snippet to define a setting::
+
+   [rattail]
+   app_title = Poser
+
+But then that same setting is written in SQL as:
+
+.. code-block:: sql
+
+   insert into setting (name, value) values ('rattail.app_title', 'Poser');
+
+In other words the "section" and "option" names from the config file, are
+joined together with a dot, for the DB setting name.
+
+When the app requests a config value, it must specify both a section and
+option.  The config engine then will auto-join them as needed when doing DB
+lookups.
+
+.. code-block:: python
+
+   config.get('rattail', 'app_title')
+
+
+Avoiding the DB
+---------------
+
+The app can request config from "file only" if it needs to.  It just has to
+specify a flag when reading the value, for example:
+
+.. code-block:: python
+
+   config.get('rattail', 'app_title', usedb=False)