Doc: commit performs rollback of aborted transactions.

The COMMIT command handles an aborted transaction in the same
manner as the ROLLBACK command, but this wasn't explained in
its official reference page.  Also mention that behavior in
the tutorial's material on transactions.

Also add a comment mentioning that we don't raise an exception
for COMMIT within an aborted transaction, as the SQL standard
would have us do.

Hyperlink a couple of cross-references while we're at it.

Author: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Gurjeet Singh <gurjeet@singh.im>
Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CAKFQuwYgYR3rWt6vFXw=ZWZ__bv7PqvdOnHujG+UyqE11f+3sg@mail.gmail.com

diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 451bcb202ec6f79458cd8d176463a5ada5eee722..3286c2cf0b26f8419ccf5f364cc904e7c6ad4f4a 100644 (file)
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -149,7 +149,7 @@ 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 an error occurs that prevents the transaction from completing,
     then none of the steps affect the database at all.
    </para>
 
@@ -218,7 +218,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 +234,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 +257,17 @@ COMMIT;
     </para>
    </note>
 
+   <para>
+    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 rejected.  Importantly, both those
+    commands will behave identically &mdash; they roll back and close the
+    failed transaction, returning the session to a state where new commands
+    can be issued.  They will also automatically begin a new transaction if
+    executed with the <literal>AND CHAIN</literal> option.
+   </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

diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml
index 7e2dcac5a33a2e76e2909d33c3edf40c4f2d6a37..3234033de3fe732f4b44f63cee826896126f43d4 100644 (file)
--- a/doc/src/sgml/ref/commit.sgml
+++ b/doc/src/sgml/ref/commit.sgml
@@ -33,6 +33,22 @@ 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 case, if the <literal>AND CHAIN</literal> parameter is
+   specified then a new, identically configured, transaction is started.
+  </para>
+
+  <para>
+   For more information regarding transactions see
+   <xref linkend="tutorial-transactions"/>.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -67,6 +83,25 @@ COMMIT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
   </variablelist>
  </refsect1>
 
+ <refsect1>
+  <title>Outputs</title>
+
+  <para>
+   On successful completion of a non-aborted transaction,
+   a <command>COMMIT</command> command returns a command tag of the form
+<screen>
+COMMIT
+</screen>
+  </para>
+  <para>
+   However, in 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 +131,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 the transaction
+   was already aborted.
+  </para>
+
+  <para>
+   The form <literal>COMMIT TRANSACTION</literal> is a PostgreSQL extension.
   </para>
  </refsect1>
 
@@ -107,6 +147,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>