On Wed, Jan 1, 2025 at 11:16 PM Gurjeet Singh <gurj...@singh.im> wrote:
> > On Fri, Dec 20, 2024 at 9:02 AM David G. Johnston <
> david.g.johns...@gmail.com> wrote:
>
> >> The commit reference page lacks an "Outputs" section even though it is
> capable of outputting both "COMMIT" and "ROLLBACK".
>
> I generally agree with the improvements proposed. I currently don't
> have the infrastructure to build docs, so the following review is
> without the benefit of what the build output looks like.
>
Thank you for the review. Version 2 Attached.
> This line in the patch has a trailing whitespace, which should be removed.
>
> + <xref linkend="sql-begin"/> and
>
Done
> I believe this sentence can be improved slightly:
>
> + When a failure does occur during a transaction it is not ended but
> instead
> + goes into an aborted state.
>
> as: When an error occurs in a transaction block, the transaction goes
> into an aborted state.
>
Agreed, and changed the existing usage of failure to error to match.
> So this seems like a better statement: If the transaction is in an
> aborted state, say, because of an error, then the effect of the
> <command>COMMIT</> will be identical to that of <command>ROLLBACK</>,
> including the command tag output.
>
I went with:
+ 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.
> The following needs to be rephrased:
>
> + However, if the transaction being affected is aborted, a
> <command>COMMIT</command>
> + command returns a command tag of the form
>
> as: However, if the transaction is in an aborted state, the
> <command>COMMIT</> command ...
>
I went with this, keeping the phrasing "on an" consistent between this and
the previous text.
+ However, on an aborted transaction, a <command>COMMIT</command>
+ command returns a command tag of the form
The use of "a/an" instead of "the" is supported by existing phrasing for
Insert.
"On successful completion, an INSERT command returns a command tag of the
form"
David J.
From 2bdcb8d0c5cfffcb4db8c150d568b7a98b82b422 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@gmail.com>
Date: Fri, 20 Dec 2024 08:40:47 -0700
Subject: [PATCH] doc: Commit performs rollback of aborted transactions
The Commit command handles an aborted transaction in the same
manner as the Rollback command. This needs to be documented.
Add it to both the reference page as well mentioning the behavior
in the official material for introducting transactions - the tutorial.
In passing, make the description of the Commit reference page
self-contained by mentioning the 'and chain' behavior.
---
doc/src/sgml/advanced.sgml | 18 +++++++++++++++---
doc/src/sgml/ref/commit.sgml | 33 +++++++++++++++++++++++++++++++++
2 files changed, 48 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 755c9f1485..6b82e731b9 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/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 a <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
diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml
index 7e2dcac5a3..876a971db6 100644
--- a/doc/src/sgml/ref/commit.sgml
+++ b/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>
@@ -107,6 +139,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>
--
2.34.1
