docs: improve docs relating to app db, setup thereof

docs/narr/db/app.rst

@@ -2,20 +2,105 @@
 App Database
 ============
 
-The :term:`app database` is used at minimum to contain the
-:term:`settings table`.
+The :term:`app database` is used at minimum to store the
+:term:`settings table`, but usually also has tables for other
+:term:`data models <data model>` used by the app.
 
-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.
+If you *only* want a settings table but do not need the app database
+to serve any other purpose, see :doc:`/narr/config/table`.
 
 
-Configuring the Connection
---------------------------
+.. _create-appdb:
+
+Create the Database
+-------------------
+
+There is not currently any tooling in WuttJamaican to *create* the
+database (unless using a SQLite file, which may happen automatically).
+
+PostgreSQL is the recommended backend for production, as it is the
+only one with rigorous usage thus far.  MySQL should also work though
+and you're free to experiment.  Theoretically anything supported by
+SQLAlchemy should work; see :doc:`sqlalchemy:dialects/index`.
+
+You may need to install additional Python and/or OS packages to
+support your desired backend.
+
+PostgreSQL
+~~~~~~~~~~
+
+Install APT packages if needed:
+
+.. code-block:: sh
+
+   sudo apt install postgresql libpq-dev
+
+Install Python packages (to :term:`virtual environment`) if needed:
+
+.. code-block:: sh
+
+   pip install psycopg2
+
+Make a new DB user ("myuser") if needed:
+
+.. code-block:: sh
+
+   sudo -u postgres createuser myuser
+
+And if so, also set the password:
+
+.. code-block:: sh
+
+   sudo -u postgres psql -c "ALTER USER myuser PASSWORD 'mypassword'"
+
+And finally create the DB ("myappdb" owned by "myuser"):
+
+.. code-block:: sh
+
+   sudo -u postgres createdb -O myuser myappdb
+
+MySQL
+~~~~~
+
+Install APT packages if needed:
+
+.. code-block:: sh
+
+   sudo apt install default-mysql-server
+
+Install Python packages (to :term:`virtual environment`) if needed:
+
+.. code-block:: sh
+
+   pip install mysql-connector-python
+
+Make a new DB user ("myuser") if needed:
+
+.. code-block:: sh
+
+   sudo mysql -e "CREATE USER myuser@localhost"
+
+And if so, also set the password:
+
+.. code-block:: sh
+
+   sudo mysql -e "ALTER USER myuser@localhost  IDENTIFIED BY 'mypassword'"
+
+Create the DB ("myappdb"):
+
+.. code-block:: sh
+
+   sudo mysqladmin create myappdb
+
+And grant all perms (to "myuser" for "myappdb"):
+
+.. code-block:: sh
+
+   sudo mysql -e "GRANT ALL ON myappdb.* TO myuser@localhost"
+
+
+Configure the Connection
+------------------------
 
 Once you have a database ready, add to your :term:`config file` the
 details, for example:
@@ -23,7 +108,77 @@ details, for example:
 .. code-block:: ini
 
    [wutta.db]
-   default.url = postgresql://wutta:wuttapass@localhost/wuttadb
+
+   # postgres
+   default.url = postgresql://myuser:mypassword@localhost/myappdb
+
+   # mysql
+   default.url = mysql+mysqlconnector://myuser:mypassword@localhost/myappdb
+
+You also most likely want to prefer settings from the DB over those
+found in the config file(s).  See also
+:ref:`where-config-settings-come-from` but the gist is, you should add
+this config:
+
+.. code-block:: ini
+
+   [wutta.config]
+   usedb = true
+   preferdb = true
+
+
+Install the Schema
+------------------
+
+So far there is not a tool to "create all tables" for the :term:`app
+model` in one step per se.  Rather, we use Alembic to "apply all
+migrations" to get to the latest schema.  (The end result is the
+same.)
+
+See also the :doc:`Alembic docs <alembic:index>`, but our process is
+fairly simple.
+
+First add some Alembic settings to your :term:`config file`:
+
+.. code-block:: ini
+
+   [alembic]
+   script_location = wuttjamaican.db:alembic
+   version_locations = wuttjamaican.db:alembic/versions
+
+Usually the ``script_location`` shown above will work fine, but the
+``version_locations`` may vary depending on which packages contribute
+to your overall app model.
+
+For instance a Poser app which also uses :doc:`Wutta-Continuum
+<wutta-continuum:index>` may specify this instead:
+
+.. code-block:: ini
+
+   [alembic]
+   script_location = wuttjamaican.db:alembic
+   version_locations = wutta_continuum.db:alembic/versions poser.db:alembic/versions wuttjamaican.db:alembic/versions
+
+Note that is really specifying 3 different packages, and the sequence matters (*):
+
+* ``wutta_continuum.db:alembic/versions``
+* ``poser.db:alembic/versions``
+* ``wuttjamaican.db:alembic/versions``
+
+(*) While it does seem to matter, this is not yet fully understood.
+You may need to experiment.
+
+In any case once you've added the Alembic settings you can migrate schema:
+
+.. code-block:: sh
+
+   alembic -c /path/to/my.conf upgrade heads
+
+If you have multiple packages for schema (as shown above) and you get
+errors here, you may need to try a different package sequence in
+config.
+
+But if the migration went okay then you now have a complete app database.
 
 
 Multiple Databases
@@ -39,11 +194,23 @@ Using that example, the host config might look like:
 .. code-block:: ini
 
    [wutta.db]
-   # nb. host itself is referred to as 'default'
+   # nb. the localhost ("host") node is default
    keys = default, store001, store002, store003
 
-   default.url = postgresql://wutta:wuttapos@localhost/wutta-host
+   default.url = postgresql://wutta:wuttapass@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
+   store001.url = postgresql://wutta:wuttapass@store001/wutta-store
+   store002.url = postgresql://wutta:wuttapass@store002/wutta-store
+   store003.url = postgresql://wutta:wuttapass@store003/wutta-store
+
+And to be thorough, each store config might look like:
+
+.. code-block:: ini
+
+   [wutta.db]
+   # nb. the localhost ("store") node is default
+   keys = default, host
+
+   default.url = postgresql://wutta:wuttapass@localhost/wutta-store
+
+   host.url = postgresql://wutta:wuttapass@host-server/wutta-host

docs/narr/db/index.rst

@@ -2,9 +2,21 @@
 Databases
 =========
 
-.. toctree::
-   :maxdepth: 2
+Most :term:`apps <app>` based on WuttJamaican will have an :term:`app
+database`.  This may be used to store :term:`config settings <config
+setting>` but usually, lots of other things.
+
+Each app can declare its :term:`app model` which is essentially the
+list of tables, each mapped to a Python class via SQLAlchemy ORM.  The
+default app model is :mod:`wuttjamaican.db.model`.
+
+But of course any other :term:`database(s) <database>` may be
+involved, for integration purposes etc.  So there are some
+conveniences around that too.
+
+
+.. toctree::
+   :maxdepth: 3
 
-   overview
    app
    other

docs/narr/db/overview.rst

@@ -1,13 +0,0 @@
-
-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`.