From 9b45f8b97cfad82d42fc01a04f2ec5640cd231de Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Thu, 14 May 2026 17:27:11 +0000 Subject: [PATCH] Document the transaction concept --- doc/src/epilog.inc.m4 | 4 ++++ doc/src/intro/about_db.m4 | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/doc/src/epilog.inc.m4 b/doc/src/epilog.inc.m4 index e45732d..8235e9c 100644 --- a/doc/src/epilog.inc.m4 +++ b/doc/src/epilog.inc.m4 @@ -556,6 +556,10 @@ sdb_generated_rst()dnl This column must contain values that fall on one minute intervals; it may not contain values having seconds or fractions of seconds. +.. |transaction commit| replace:: + This condition is checked on :ref:`transaction commit + `. + .. Substitutions, used to give labels to internal links .. The upload schema, which is not yet documented diff --git a/doc/src/intro/about_db.m4 b/doc/src/intro/about_db.m4 index 1523128..baca6a0 100644 --- a/doc/src/intro/about_db.m4 +++ b/doc/src/intro/about_db.m4 @@ -146,6 +146,40 @@ Schemas organize database content. One purpose is to allow a user to focus on the content of some schema(s) and ignore what is in other schemas. + +.. _about_transactions: + +About Transactions +`````````````````` + +A database transaction is a series of data content alterations that +either all succeed, or fail to alter the content of the database in +any way. +Because SokweDB has `transaction isolation`_, data alterations that +occur within a transaction are not visible to concurrent database +users. +That is to say, they are not visible unless the transaction completes +successfully. + +Transactions are completed by "committing" them. +At that point they either succeed or fail. + +It is possible to interact with PostgreSQL_ in such a way that +multiple violations of SokweDB's data integrity rules, violations that +all occur within a single transaction, are reported. +Of course, when this happens the transaction fails and the database +content is not changed. + +But, some of SokweDB's data integrity rules are checked at transaction +commit time. +It is not possible to report more than one violation of data integrity +rules that are checked at transaction commit time. + +This impacts the bulk-loading of data into SokweDB and the procedures +that may involve discovering and correcting errors in the data when +bulk-loading. + + .. rubric:: Footnotes .. [#f1] The term "schema" is overloaded. A separate meaning defines -- 2.34.1