3
0
Fork 0

docs: improve docs relating to app db, setup thereof

This commit is contained in:
Lance Edgar 2024-12-08 12:19:42 -06:00
parent d70df11be6
commit 45ea5c5bdc
9 changed files with 241 additions and 74 deletions

View file

@ -30,7 +30,8 @@ Make and activate a new :term:`virtual environment` for your project:
python3 -m venv poser
source poser/bin/activate
Make a new e.g. ``poser`` database in PostgreSQL (or MySQL).
Make a new e.g. ``poser`` database in PostgreSQL (or MySQL). Nothing
special here but for instructions see :ref:`create-appdb`.
Install and run `cookiecutter <https://cookiecutter.readthedocs.io/>`_
with `wuttaweb template
@ -75,7 +76,7 @@ the package with:
.. code-block:: sh
pip install wuttjamaican
pip install WuttJamaican[db]
Create a :term:`config file`, e.g. ``my.conf``:
@ -125,6 +126,7 @@ For more info see:
* :func:`~wuttjamaican.conf.make_config()`
* :class:`~wuttjamaican.conf.WuttaConfig` and especially
:meth:`~wuttjamaican.conf.WuttaConfig.get()`
* :class:`~wuttjamaican.app.AppHandler`
.. _db-setup:
@ -134,20 +136,9 @@ 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.
within the DB backend. This is pretty routine but for instructions
see :ref:`create-appdb`.
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
@ -163,8 +154,6 @@ shown above). Contents for this will look something like (using
# 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:
@ -178,8 +167,17 @@ 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
alembic -c /path/to/my.conf upgrade heads
Now you should have all the tables required for a WuttJamaican
:term:`app database`.
If you wish to store :term:`config settings <config setting>` in the
DB, don't forget to add to your config file (see also
:ref:`where-config-settings-come-from`):
.. code-block:: ini
[wutta.config]
usedb = true
preferdb = true