From 4a9fe3568948c9cf031172be7f62a83fa71a9437 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Sat, 22 Feb 2025 19:46:40 +0000 Subject: [PATCH] Update codes schema docs to mention the functions it holds --- doc/src/architecture/schemas.m4 | 34 ++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/doc/src/architecture/schemas.m4 b/doc/src/architecture/schemas.m4 index 136206c..4d0b4e9 100644 --- a/doc/src/architecture/schemas.m4 +++ b/doc/src/architecture/schemas.m4 @@ -35,15 +35,17 @@ The sokwedb schema The ``sokwedb`` schema contains the data collected in the field. It is the primary schema of interest to the researcher. + The codes schema ```````````````` +The ``codes`` schema exists so that the ``sokwedb`` schema is not +cluttered with un-interesting tables, and other things.\ [#f1]_ + The ``codes`` schema contains those tables which control the data vocabulary defining the codes able to be recorded in the database. Because the codes defined in this schema are often used and well-known -the schema's tables are not often of interest. This schema exists so -that the ``sokwedb`` schema is not cluttered with un-interesting -tables. +the schema's tables are not often of interest. Most of the tables in this schema contain one row per defined code. The codes are usually kept in a column that has the name of @@ -56,6 +58,9 @@ information' involving the mechanics of the data collection process. Things like lists of researchers, observers, or equipment used in the data collection process. +The ``codes`` schema also contains functions and other tools used to +administer the system.\ [#f2]_ + The upload schema ````````````````` @@ -92,3 +97,26 @@ qualify anything created in the user's schema. E.g., to create the table ``foo`` in the user ``mylogin``'s schema:: CREATE TABLE mylogin.foo (somecolumn INTEGER); + + +.. _materialized view: + https://www.postgresql.org/docs/current/rules-materializedviews.html + +.. rubric:: Footnotes + +.. [#f1] The ``codes`` schema might be better named "administration", + but that name is too long to type. + +.. [#f2] Every data structure, think `materialized view`_ or other + constructed table content, that is automatically constructed + by the system's triggers should always have, as an alternate + approach, a way be manually rebuilt. + That way, should the triggers ever fail to operate properly, + there is a way to recover. + In addition, a second method provides a check against with + both methods can be tested to be sure that the results are as + expected. + + Providing a function for every such constructed table, or + other constructed data, that rebuilds the table, provides a + way for the the reconstruction to be done manually. -- 2.34.1