From e855a84c37fa6e9f09989ba7b50d7b54edd9437c Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Fri, 23 Aug 2024 15:20:38 -0500
Subject: [PATCH] docs: add basic db setup to quickstart doc

---
 docs/narr/install/quickstart.rst | 85 ++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 5 deletions(-)

diff --git a/docs/narr/install/quickstart.rst b/docs/narr/install/quickstart.rst
index 821957e..c8be0e3 100644
--- a/docs/narr/install/quickstart.rst
+++ b/docs/narr/install/quickstart.rst
@@ -2,13 +2,19 @@
 Quick Start
 ===========
 
-Install with:
+This shows the *minimum* use case, basically how to make/use the
+:term:`config object` and :term:`app handler`.
+
+(See next section for :ref:`db-setup`.)
+
+You should have already made a :term:`virtual environment`.  Install
+the package with:
 
 .. code-block:: sh
 
    pip install wuttjamaican
 
-Create a config file, e.g. ``my.conf``:
+Create a :term:`config file`, e.g. ``my.conf``:
 
 .. code-block:: ini
 
@@ -18,7 +24,8 @@ Create a config file, e.g. ``my.conf``:
    feature = true
    words = the quick brown fox
 
-In your app, load the config and reference its values as needed::
+In code, load the config and reference its values as needed, and/or
+invoke other app/handler logic::
 
    from wuttjamaican.conf import make_config
 
@@ -37,11 +44,79 @@ In your app, load the config and reference its values as needed::
    config.get('foo.words')              # 'the quick brown fox'
    config.get_list('foo.words')         # ['the', 'quick', 'brown', 'fox']
 
+   # now for the app handler..and interacting with DB
+   app = config.get_app()
+   model = app.model
+   session = app.make_session()
+
+   # invoke secondary handler to make new user account
+   auth = app.get_auth_handler()
+   user = auth.make_user(session=session, username='barney')
+
+   # commit changes to DB
+   session.add(user)
+   session.commit()
+
 For more info see:
 
 * :func:`~wuttjamaican.conf.make_config()`
 * :class:`~wuttjamaican.conf.WuttaConfig` and especially
   :meth:`~wuttjamaican.conf.WuttaConfig.get()`
 
-You can also define your own command line interface; see
-:doc:`/narr/cli/index`.
+
+.. _db-setup:
+
+Database Setup
+==============
+
+You should already have the package installed (see previous section).
+
+You also must install some package(s) for the particular database
+backend you wish to use.  PostgreSQL is recommended although MySQL
+etc. should also work.  For instance:
+
+.. code-block:: sh
+
+   # postgres
+   pip install psycopg2
+
+   # mysql
+   pip install mysql-connector-python
+
+Next you must create the database, as well as any user account needed,
+within the DB backend.
+
+Now add the DB info to your :term:`config file` (e.g. ``my.conf`` as
+shown above).  Contents for this will look something like (using
+``poserdb`` as the DB name):
+
+.. code-block:: ini
+
+   [wutta.db]
+
+   # postgres
+   default.url = postgresql://USERNAME:PASSWORD@localhost/poserdb
+
+   # mysql
+   default.url = mysql+mysqlconnector://USERNAME:PASSWORD@localhost/poserdb
+
+See :doc:`/narr/db/app` for more about that.
+
+You also must add some Alembic config, needed for DB schema
+migrations:
+
+.. code-block:: ini
+
+   [alembic]
+   script_location = wuttjamaican.db:alembic
+   version_locations = wuttjamaican.db:alembic/versions
+
+With config file updated you can run the Alembic command to migrate schema:
+
+.. code-block:: sh
+
+   cd /path/to/env
+   bin/alembic -c /path/to/my.conf upgrade heads
+
+Now you should have all the tables required for a WuttJamaican
+:term:`app database`.