[CF 5546] v3 - Document how commit handles aborted transactions

This branch was automatically generated by a robot using patches from an
email thread registered at:

https://commitfest.postgresql.org/patch/5546

The branch will be overwritten each time a new patch version is posted to
the thread, and also periodically to check for bitrot caused by changes
on the master branch.

Patch(es): https://www.postgresql.org/message-id/CAKFQuwaOevyJo8E7wi4Tp2MB5C+8v92ThbMPFFjheDFgfYvgLA@mail.gmail.com
Author(s): David Johnston

Author: Commitfest Bot

doc/src/sgml/advanced.sgml

@@ -149,7 +149,8 @@ DETAIL:  Key (city)=(Berkeley) is not present in table "cities".
     systems.  The essential point of a transaction is that it bundles
     multiple steps into a single, all-or-nothing operation.  The intermediate
     states between the steps are not visible to other concurrent transactions,
-    and if some failure occurs that prevents the transaction from completing,
+    and if <link linkend="tutorial-transactions-aborted">an error</link>
+    occurs that prevents the transaction from completing,
     then none of the steps affect the database at all.
    </para>
 
@@ -218,7 +219,8 @@ UPDATE branches SET balance = balance + 100.00
    <para>
     In <productname>PostgreSQL</productname>, a transaction is set up by surrounding
     the SQL commands of the transaction with
-    <command>BEGIN</command> and <command>COMMIT</command> commands.  So our banking
+    <xref linkend="sql-begin"/> and
+    <xref linkend="sql-commit"/> commands.  So our banking
     transaction would actually look like:
 
 <programlisting>
@@ -233,7 +235,7 @@ COMMIT;
    <para>
     If, partway through the transaction, we decide we do not want to
     commit (perhaps we just noticed that Alice's balance went negative),
-    we can issue the command <command>ROLLBACK</command> instead of
+    we can issue the command <xref linkend="sql-rollback"/> instead of
     <command>COMMIT</command>, and all our updates so far will be canceled.
    </para>
 
@@ -256,6 +258,16 @@ COMMIT;
     </para>
    </note>
 
+   <para id="tutorial-transactions-aborted">
+    When an error occurs within a transaction block the transaction is not ended
+    but instead goes into an aborted state.  While in this state all commands except
+    <xref linkend="sql-commit"/> and <xref linkend="sql-rollback"/> are ignored and,
+    importantly, both those commands behave identically - they roll-back and close
+    the current transaction, returning the session to a state where new commands can
+    be issued.  They will also automatically begin a new transaction if executed
+    with an <literal>AND CHAIN</literal> parameter.
+   </para>
+
    <para>
     It's possible to control the statements in a transaction in a more
     granular fashion through the use of <firstterm>savepoints</firstterm>.  Savepoints

doc/src/sgml/ref/commit.sgml

@@ -33,6 +33,19 @@ COMMIT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
    changes made by the transaction become visible to others
    and are guaranteed to be durable if a crash occurs.
   </para>
+  <para>
+   If the transaction is in an aborted state then no changes will be made
+   and the effect of the <command>COMMIT</command> will be identical to that
+   of <command>ROLLBACK</command>, including the command tag output.
+  </para>
+  <para>
+   In either situation, if the <literal>AND CHAIN</literal> parameter is
+   specified a new, identically configured, transaction is started.
+  </para>
+  <para>
+   For more information regarding transactions see
+   <xref linkend="tutorial-transactions"/>.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -67,6 +80,25 @@ COMMIT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Outputs</title>
+
+  <para>
+   On successful completion on a non-aborted transaction, a <command>COMMIT</command>
+   command returns a command tag of the form
+<screen>
+COMMIT
+</screen>
+  </para>
+  <para>
+   However, on an aborted transaction, a <command>COMMIT</command>
+   command returns a command tag of the form
+<screen>
+ROLLBACK
+</screen>
+  </para>
+ </refsect1>
+
  <refsect1>
   <title>Notes</title>
 
@@ -96,8 +128,13 @@ COMMIT;
   <title>Compatibility</title>
 
   <para>
-   The command <command>COMMIT</command> conforms to the SQL standard.  The
-   form <literal>COMMIT TRANSACTION</literal> is a PostgreSQL extension.
+   The command <command>COMMIT</command> conforms to the SQL standard, except
+   that no exception condition is raised in the case where an already aborted
+   transaction is committed.
+  </para>
+
+  <para>
+   The form <literal>COMMIT TRANSACTION</literal> is a PostgreSQL extension.
   </para>
  </refsect1>
 
@@ -107,6 +144,7 @@ COMMIT;
   <simplelist type="inline">
    <member><xref linkend="sql-begin"/></member>
    <member><xref linkend="sql-rollback"/></member>
+   <member><xref linkend="tutorial-transactions"/></member>
   </simplelist>
  </refsect1>
 </refentry>