.. 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)