From c7f585dfed9eabd1544adc28b9b81ec3258b7703 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Mon, 8 Aug 2022 15:31:28 -0500
Subject: [PATCH] Add notes on beaker config caching

---
 docs/base/config/db.rst | 70 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/docs/base/config/db.rst b/docs/base/config/db.rst
index ce668cd..74020b8 100644
--- a/docs/base/config/db.rst
+++ b/docs/base/config/db.rst
@@ -48,9 +48,9 @@ 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.
+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::
 
@@ -84,3 +84,67 @@ specify a flag when reading the value, for example:
 .. code-block:: python
 
    config.get('rattail', 'app_title', usedb=False)
+
+
+DB Settings Cache
+-----------------
+
+One downside of reading config values from the DB settings table, is
+the number of queries involved, as each call to ``config.get()`` would
+normally involve a separate SQL query.  (Not only that, but unless a
+DB session is passed to ``config.get()`` a new one will be made just
+for the query.)
+
+To help with this, you can enable caching for the DB settings.  This
+should "just work" as expected; i.e. calls to ``config.get()`` need
+not change.  (Although there's no point in passing a DB session when
+caching is enabled.)
+
+To turn on the caching, add to your config file::
+
+   [rattail.config]
+   beaker_cache.enabled = true
+
+By default this cache will be file-based, storage for which is at
+e.g. ``/srv/envs/poser/app/cache/config/`` although you can override
+the paths if you prefer::
+
+   [rattail.config]
+   beaker_cache.enabled = true
+   beaker_cache.data_dir = /somewhere/else/data
+   beaker_cache.lock_dir = /somewhere/else/lock
+
+memcached
+=========
+
+If you're not crazy about caching to disk and would prefer to use
+`memcached`_ as the backend instead, first install that:
+
+.. _memcached: https://www.memcached.org/
+
+.. code-block:: sh
+
+   sudo apt install memcached
+
+Then install the Python dependencies to your virtual environment:
+
+.. code-block:: sh
+
+   cd /srv/envs/poser
+   source bin/activate
+   pip install 'rattail[memcached]'
+
+And finally add to your config file::
+
+   [rattail.config]
+   beaker_cache.enabled = true
+   beaker_cache.type = ext:memcached
+   beaker_cache.url = 127.0.0.1:11211
+
+Rattail will try to come up with a unique namespace to use for the
+cache; this is needed in situations where the same ``memcached``
+service is handling multiple "separate" Rattail apps.  You can also
+explicitly set the namespace to use, e.g.::
+
+   [rattail.config]
+   beaker_cache.namespace = my_custom_namespace