diff --git a/docs/glossary.rst b/docs/glossary.rst index 03a287a..f1a52e2 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -95,7 +95,8 @@ Glossary settings table Table in the :term:`app database` which is used to store - :term:`config settings`. + :term:`config settings`. See also + :doc:`narr/config/table`. subcommand A top-level :term:`command` may expose one or more subcommands, diff --git a/docs/narr/config/index.rst b/docs/narr/config/index.rst index 0051009..b96c324 100644 --- a/docs/narr/config/index.rst +++ b/docs/narr/config/index.rst @@ -9,3 +9,4 @@ Configuration settings object files + table diff --git a/docs/narr/config/overview.rst b/docs/narr/config/overview.rst index 0919f01..0a4c196 100644 --- a/docs/narr/config/overview.rst +++ b/docs/narr/config/overview.rst @@ -9,7 +9,11 @@ The app must call :func:`~wuttjamaican.conf.make_config()` during startup to obtain the config object. Values come (mostly) from :term:`config files` and/or the -:term:`settings table`. See also :doc:`settings`. +:term:`settings table`. For more about those see: + +* :doc:`settings` +* :doc:`files` +* :doc:`table` Values are always strings in their raw format, as returned by :meth:`~wuttjamaican.conf.WuttaConfig.get()`. But the config object diff --git a/docs/narr/config/table.rst b/docs/narr/config/table.rst new file mode 100644 index 0000000..17278b7 --- /dev/null +++ b/docs/narr/config/table.rst @@ -0,0 +1,74 @@ + +Settings Table +============== + +Sometimes the :term:`config settings` may come from a +:term:`settings table` as opposed to :term:`config file`. + +The settings table resides in the :term:`app database`. + +Note that as of writing, the WuttJamaican package *does not address* +how to create or setup the app database. However it does have the +ability to query the settings table if present. + + +Table Structure +--------------- + +Currently the table *must* be named ``setting`` and have (at least) 2 +columns, ``name`` and ``value``: + +.. code-block:: sql + + CREATE TABLE setting ( + name VARCHAR(255) NOT NULL PRIMARY KEY, + value TEXT + ); + + +Configuring the DB Connection +----------------------------- + +You must add some entries to your config file, to tell the app where +its database lives, and that it should be used for this purpose: + +.. code-block:: ini + + [wutta.config] + usedb = true + preferdb = true + + [wutta.db] + default.url = postgresql://wutta:wuttapass@localhost/wuttadb + +This uses `SQLAlchemy`_ under the hood, so it should support anything +that does; see also +:meth:`~wuttjamaican.app.AppHandler.make_engine_from_config()`. + +.. _SQLAlchemy: https://www.sqlalchemy.org + +See :ref:`where-config-settings-come-from` for more about the +``usedb`` and ``preferdb`` flags. + + +Querying the Table +------------------ + +Normally there is no need to query directly, but rather the +:term:`config object` may do so automatically. + +Assuming the config object knows to look in the settings table, then +it's just a matter of calling its normal +:meth:`~wuttjamaican.conf.WuttaConfig.get()` and similar methods:: + + from wuttjamaican.conf import make_config + + config = make_config() + + config.get('foo.bar') + config.get_bool('foo.flag') + +If your config object does *not* check the settings table by default, +you can always ask it to explicitly:: + + config.get('foo.bar', usedb=True, preferdb=True) diff --git a/src/wuttjamaican/app.py b/src/wuttjamaican/app.py index 9f2f64b..bb18f3a 100644 --- a/src/wuttjamaican/app.py +++ b/src/wuttjamaican/app.py @@ -104,7 +104,10 @@ class AppHandler: Construct a new DB engine from configuration dict. This is a wrapper around upstream - :func:`sqlalchemy:sqlalchemy.engine_from_config()`. + :func:`sqlalchemy:sqlalchemy.engine_from_config()`. For even + broader context of the SQLAlchemy + :class:`~sqlalchemy:sqlalchemy.engine.Engine` and their + configuration, see :doc:`sqlalchemy:core/engines`. The purpose of the customization is to allow certain attributes of the engine to be driven by config, whereas the