doc: add transaction processing chapter with internals info

This also adds references to this new chapter at relevant sections of our documentation. Previously much of these internal details were exposed to users, but not explained. This also updates RELEASE SAVEPOINT. Discussion: https://postgr.es/m/CANbhV-E_iy9fmrErxrCh8TZTyenpfo72Hf_XD2HLDppva4dUNA@mail.gmail.com Author: Simon Riggs, Laurenz Albe Reviewed-by: Bruce Momjian Backpatch-through: 11
postgres · Nov 30, 2022 · 7b96f52 · 7b96f52
1 parent 20b796a
commit 7b96f52
Show file tree

Hide file tree

Showing 11 changed files with 266 additions and 36 deletions.
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
@@ -9187,16 +9187,17 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry></entry>
       <entry>
        Virtual ID of the transaction targeted by the lock,
-       or null if the target is not a virtual transaction ID
+       or null if the target is not a virtual transaction ID;  see
+       <xref linkend="transactions"/>
       </entry>
      </row>
      <row>
       <entry><structfield>transactionid</structfield></entry>
       <entry><type>xid</type></entry>
       <entry></entry>
       <entry>
-       ID of the transaction targeted by the lock,
-       or null if the target is not a transaction ID
+       ID of the transaction targeted by the lock, or null if the target
+       is not a transaction ID;  <xref linkend="transactions"/>
       </entry>
      </row>
      <row>

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -6566,12 +6566,14 @@ local0.*    /var/log/postgresql
             </row>
             <row>
              <entry><literal>%v</literal></entry>
-             <entry>Virtual transaction ID (backendID/localXID)</entry>
+             <entry>Virtual transaction ID (backendID/localXID);  see
+             <xref linkend="transaction-id"/></entry>
              <entry>no</entry>
             </row>
             <row>
              <entry><literal>%x</literal></entry>
-             <entry>Transaction ID (0 if none is assigned)</entry>
+             <entry>Transaction ID (0 if none is assigned);  see
+             <xref linkend="transaction-id"/></entry>
              <entry>no</entry>
             </row>
             <row>

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
@@ -101,6 +101,7 @@
 <!ENTITY protocol   SYSTEM "protocol.sgml">
 <!ENTITY sources    SYSTEM "sources.sgml">
 <!ENTITY storage    SYSTEM "storage.sgml">
+<!ENTITY transaction     SYSTEM "xact.sgml">
 <!ENTITY tablesample-method SYSTEM "tablesample-method.sgml">
 <!ENTITY generic-wal SYSTEM "generic-wal.sgml">
 

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
@@ -817,7 +817,8 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
     <row>
      <entry><structfield>backend_xid</structfield></entry>
      <entry><type>xid</type></entry>
-     <entry>Top-level transaction identifier of this backend, if any.</entry>
+     <entry>Top-level transaction identifier of this backend, if any;  see
+      <xref linkend="transaction-id"/>.</entry>
     </row>
     <row>
      <entry><structfield>backend_xmin</structfield></entry>

diff --git a/doc/src/sgml/pgrowlocks.sgml b/doc/src/sgml/pgrowlocks.sgml
@@ -57,7 +57,8 @@ pgrowlocks(text) returns setof record
      <row>
       <entry><structfield>locker</structfield></entry>
       <entry><type>xid</type></entry>
-      <entry>Transaction ID of locker, or multixact ID if multitransaction</entry>
+      <entry>Transaction ID of locker, or multixact ID if
+      multitransaction;  see <xref linkend="transaction-id"/></entry>
      </row>
      <row>
       <entry><structfield>multi</structfield></entry>

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
@@ -260,6 +260,7 @@
   &brin;
   &hash;
   &storage;
+  &transaction;
   &bki;
   &planstats;
 

diff --git a/doc/src/sgml/ref/release_savepoint.sgml b/doc/src/sgml/ref/release_savepoint.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>RELEASE SAVEPOINT</refname>
-  <refpurpose>destroy a previously defined savepoint</refpurpose>
+  <refpurpose>release a previously defined savepoint</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -34,23 +34,13 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
   <title>Description</title>
 
   <para>
-   <command>RELEASE SAVEPOINT</command> destroys a savepoint previously defined
-   in the current transaction.
-  </para>
-
-  <para>
-   Destroying a savepoint makes it unavailable as a rollback point,
-   but it has no other user visible behavior.  It does not undo the
-   effects of commands executed after the savepoint was established.
-   (To do that, see <xref linkend="sql-rollback-to"/>.)
-   Destroying a savepoint when
-   it is no longer needed allows the system to reclaim some resources
-   earlier than transaction end.
-  </para>
-
-  <para>
-   <command>RELEASE SAVEPOINT</command> also destroys all savepoints that were
-   established after the named savepoint was established.
+   <command>RELEASE SAVEPOINT</command> releases the named savepoint and
+   all active savepoints that were created after the named savepoint,
+   and frees their resources.  All changes made since the creation of
+   the savepoint that didn't already get rolled back are merged into
+   the transaction or savepoint that was active when the named savepoint
+   was created.  Changes made after <command>RELEASE SAVEPOINT</command>
+   will also be part of this active transaction or savepoint.
   </para>
  </refsect1>
 
@@ -62,7 +52,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
     <term><replaceable>savepoint_name</replaceable></term>
     <listitem>
      <para>
-      The name of the savepoint to destroy.
+      The name of the savepoint to release.
      </para>
     </listitem>
    </varlistentry>
@@ -78,7 +68,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
 
   <para>
    It is not possible to release a savepoint when the transaction is in
-   an aborted state.
+   an aborted state;  to do that, use <xref linkend="sql-rollback-to"/>.
   </para>
 
   <para>
@@ -93,7 +83,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
   <title>Examples</title>
 
   <para>
-   To establish and later destroy a savepoint:
+   To establish and later release a savepoint:
 <programlisting>
 BEGIN;
     INSERT INTO table1 VALUES (3);
@@ -104,6 +94,36 @@ COMMIT;
 </programlisting>
    The above transaction will insert both 3 and 4.
   </para>
+
+  <para>
+   A more complex example with multiple nested subtransactions:
+<programlisting>
+BEGIN;
+    INSERT INTO table1 VALUES (1);
+    SAVEPOINT sp1;
+    INSERT INTO table1 VALUES (2);
+    SAVEPOINT sp2;
+    INSERT INTO table1 VALUES (3);
+    RELEASE SAVEPOINT sp2;
+    INSERT INTO table1 VALUES (4))); -- generates an error
+</programlisting>
+   In this example, the application requests the release of the savepoint
+   <literal>sp2</literal>, which inserted 3.  This changes the insert's
+   transaction context to <literal>sp1</literal>.  When the statement
+   attempting to insert value 4 generates an error, the insertion of 2 and
+   4 are lost because they are in the same, now-rolled back savepoint,
+   and value 3 is in the same transaction context.  The application can
+   now only choose one of these two commands, since all other commands
+   will be ignored:
+<programlisting>
+   ROLLBACK;
+   ROLLBACK TO SAVEPOINT sp1;
+</programlisting>
+   Choosing <command>ROLLBACK</command> will abort everything, including
+   value 1, whereas <command>ROLLBACK TO SAVEPOINT sp1</command> will retain
+   value 1 and allow the transaction to continue.
+  </para>
+
  </refsect1>
 
  <refsect1>

diff --git a/doc/src/sgml/ref/rollback.sgml b/doc/src/sgml/ref/rollback.sgml
@@ -56,10 +56,10 @@ ROLLBACK [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
     <term><literal>AND CHAIN</literal></term>
     <listitem>
      <para>
-      If <literal>AND CHAIN</literal> is specified, a new transaction is
-      immediately started with the same transaction characteristics (see <xref
-      linkend="sql-set-transaction"/>) as the just finished one.  Otherwise,
-      no new transaction is started.
+      If <literal>AND CHAIN</literal> is specified, a new (not aborted)
+      transaction is immediately started with the same transaction
+      characteristics (see <xref linkend="sql-set-transaction"/>) as the
+      just finished one.  Otherwise, no new transaction is started.
      </para>
     </listitem>
    </varlistentry>

diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml
@@ -35,8 +35,9 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re
 
   <para>
    Roll back all commands that were executed after the savepoint was
-   established.  The savepoint remains valid and can be rolled back to
-   again later, if needed.
+   established and then start a new subtransaction at the same transaction level.
+   The savepoint remains valid and can be rolled back to again later,
+   if needed.
   </para>
 
   <para>

diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
@@ -4,8 +4,9 @@
  <title>Reliability and the Write-Ahead Log</title>
 
  <para>
-  This chapter explains how the Write-Ahead Log is used to obtain
-  efficient, reliable operation.
+  This chapter explains how to control the reliability of
+  <productname>PostgreSQL</productname>, including details about the
+  Write-Ahead Log.
  </para>
 
  <sect1 id="wal-reliability">
@@ -811,4 +812,5 @@
    seem to be a problem in practice.
   </para>
  </sect1>
+
 </chapter>