diff --git a/docs/glossary.rst b/docs/glossary.rst index 634938c..b74d12e 100644 --- a/docs/glossary.rst +++ b/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` 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. diff --git a/docs/index.rst b/docs/index.rst index b5f37cf..3f20a4d 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/narr/db/app.rst b/docs/narr/db/app.rst new file mode 100644 index 0000000..e4263f1 --- /dev/null +++ b/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 diff --git a/docs/narr/db/index.rst b/docs/narr/db/index.rst new file mode 100644 index 0000000..952db21 --- /dev/null +++ b/docs/narr/db/index.rst @@ -0,0 +1,10 @@ + +Databases +========= + +.. toctree:: + :maxdepth: 2 + + overview + app + other diff --git a/docs/narr/db/other.rst b/docs/narr/db/other.rst new file mode 100644 index 0000000..9b17c38 --- /dev/null +++ b/docs/narr/db/other.rst @@ -0,0 +1,78 @@ + +Other Databases +=============== + +Connecting to "external" (non-app) :term:`databases` +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']) diff --git a/docs/narr/db/overview.rst b/docs/narr/db/overview.rst new file mode 100644 index 0000000..2d78d41 --- /dev/null +++ b/docs/narr/db/overview.rst @@ -0,0 +1,13 @@ + +Overview +======== + +A :term:`database` is usually involved for "serious" +:term:`apps`. + +In particular an :term:`app database` may be needed to store +:term:`config settings` 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`. diff --git a/docs/narr/index.rst b/docs/narr/index.rst index 04c4268..74a3de5 100644 --- a/docs/narr/index.rst +++ b/docs/narr/index.rst @@ -9,3 +9,4 @@ Documentation config/index cli/index handlers/index + db/index