Add basic database docs

docs/glossary.rst

@@ -15,9 +15,10 @@ Glossary
      overall, or the :term:`app name`, or the :term:`app handler`.
 
    app database
-     The main database used by the :term:`app`.  There is normally
-     just one database (for simple apps) which uses PostgreSQL for the
-     backend.
+     The main :term:`database` used by the :term:`app`.  There is
+     normally just one database (for simple apps) which uses
+     PostgreSQL for the backend.  The app database contains the
+     :term:`settings table`.
 
    app dir
      Folder containing app-specific config files, log files, etc.
@@ -74,6 +75,15 @@ Glossary
      values obtained from the :term:`settings table` as opposed to
      :term:`config file`.  See also :doc:`narr/config/settings`.
 
+   database
+     Generally refers to a relational database which may be queried
+     using SQL.  More specifically, one supported by `SQLAlchemy`_.
+
+     .. _SQLAlchemy: https://www.sqlalchemy.org
+
+     Most :term:`apps<app>` will have at least one :term:`app
+     database`.
+
    entry point
      This refers to a "setuptools-style" entry point specifically,
      which is a mechanism used to register "plugins" and the like.

docs/index.rst

@@ -30,6 +30,9 @@ Features
 * flexible command line interface, with arbitrary top-level and
   subcommands
 * flexible architecture, abstracting various portions of the overall app
+* flexible database support, using `SQLAlchemy`_
+
+.. _SQLAlchemy: https://www.sqlalchemy.org
 
 
 Contents

docs/narr/db/app.rst

@@ -0,0 +1,49 @@
+
+App Database
+============
+
+The :term:`app database` is used at minimum to contain the
+:term:`settings table`.
+
+There is not yet support within WuttJamaican for the creation or setup
+of the app database.  So for now you're on your own with that.
+
+See also :doc:`/narr/config/table`.
+
+Note that while any database supported by SQLAlchemy may be used, docs
+will generally assume PostgreSQL is being used.
+
+
+Configuring the Connection
+--------------------------
+
+Once you have a database ready, add to your :term:`config file` the
+details, for example:
+
+.. code-block:: ini
+
+   [wutta.db]
+   default.url = postgresql://wutta:wuttapass@localhost/wuttadb
+
+
+Multiple Databases
+------------------
+
+Some scenarios may require multiple app databases.  A notable example
+would be a multi-store retail environment, where each store runs a
+separate app but a "host" (master) node has connections to all store
+databases.
+
+Using that example, the host config might look like:
+
+.. code-block:: ini
+
+   [wutta.db]
+   # nb. host itself is referred to as 'default'
+   keys = default, store001, store002, store003
+
+   default.url = postgresql://wutta:wuttapos@localhost/wutta-host
+
+   store001.url = postgresql://wutta:wuttapos@store001/wutta-store
+   store002.url = postgresql://wutta:wuttapos@store002/wutta-store
+   store003.url = postgresql://wutta:wuttapos@store003/wutta-store

docs/narr/db/index.rst

@@ -0,0 +1,10 @@
+
+Databases
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   app
+   other

docs/narr/db/other.rst

@@ -0,0 +1,78 @@
+
+Other Databases
+===============
+
+Connecting to "external" (non-app) :term:`databases<database>`
+essentially works the same as for the :term:`app database`.
+
+
+WordPress Example
+-----------------
+
+As a somewhat contrived example, let's say the app needs to query a
+WordPress database directly.
+
+WuttJamaican only reserves a single config file section for itself,
+which may vary (per :term:`app name`) but by default is ``wutta.db``:
+
+.. code-block:: ini
+
+   [wutta.db]
+   default.url = sqlite://
+
+But any other config file section is up for grabs.  Some other
+packages may effectively reserve other sections, but if we assume
+nobody has yet reserved the ``wordpress.db`` section, might add
+something like:
+
+.. code-block:: ini
+
+   [wordpress.db]
+   default.url = mysql://wutta:wuttapass@localhost/wordpress
+
+Then in the app code you can load the connection(s) with
+:func:`~wuttjamaican.db.conf.get_engines()`::
+
+   from wuttjamaican.conf import make_config
+   from wuttjamaican.db.conf import get_engines
+
+   config = make_config()
+   engines = get_engines(config, 'wordpress.db')
+
+As you might imagine, "rinse and repeat" for other types of databases
+besides WordPress.
+
+
+Multiple Databases
+------------------
+
+As with the app database, you can have multiple databases per type.
+
+To continue with the previous example, let's say you have a
+"production" WordPress site but also a "staging" site and the app must
+query both.
+
+There should always be a "default" database chosen, so in this case
+we'll choose "production" for that:
+
+.. code-block:: ini
+
+   [wordpress.db]
+   keys = default, staging
+   default.url = mysql://wutta:wuttapass@localhost/wordpress
+   staging.url = mysql://wutta:wuttapass@localhost/wordpress_test
+
+Then in the app code you can reference both a la::
+
+   from sqlalchemy import orm
+   from wuttjamaican.conf import make_config
+   from wuttjamaican.db.conf import get_engines
+
+   config = make_config()
+   engines = get_engines(config, 'wordpress.db')
+
+   Session = orm.sessionmaker()
+   Session.configure(bind=engines['default'])
+
+   prod_sess = Session()
+   stag_sess = Session(bind=engines['staging'])

docs/narr/db/overview.rst

@@ -0,0 +1,13 @@
+
+Overview
+========
+
+A :term:`database` is usually involved for "serious"
+:term:`apps<app>`.
+
+In particular an :term:`app database` may be needed to store
+:term:`config settings<config setting>` and usually, lots of other
+things.  See :doc:`app`.
+
+But it is possible to interact with many databases, not just the app
+database.  See :doc:`other`.

docs/narr/index.rst

@@ -9,3 +9,4 @@ Documentation
    config/index
    cli/index
    handlers/index
+   db/index