Re: Document How Commit Handles Aborted Transactions - Mailing list pgsql-hackers

On Tue, Dec 31, 2024 at 12:50 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> Thoughts?
>
> On Fri, Dec 20, 2024 at 9:02 AM David G. Johnston <david.g.johnston@gmail.com> wrote:
>>
>> Hi,
>>
>> The commit reference page lacks an "Outputs" section even though it is capable of outputting both "COMMIT" and
"ROLLBACK".
>>
>> The attached adds this section, describes when each applies, and then incorporates the same into the main
descriptionfor commit as well as the transaction section of the tutorial - which presently seems to be the main
discussionarea for the topic (the Concurrency Control chapter lacks a section for this introductory material). 
>>
>> This was noted as being needed by Tom Lane back into 2006 but it never happened.
>> https://www.postgresql.org/message-id/28798.1142608067%40sss.pgh.pa.us
>>
>> It came up again when I was answering a question on Slack regarding "commit and chain" wondering whether the "and
chain"could be made conditional (i.e., could the new transaction start aborted) on whether commit outputted "commit" or
"rollback".
>>
>> Its left implied that this behavior of "rollback" is standard-conforming.  Please feel free to suggest/add language
tothe Compatibility section if this is not the case. 

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.

This line in the patch has a trailing whitespace, which should be removed.

+    <xref linkend="sql-begin"/> and

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.

This borrows the term 'transaction block' introduced in the previous
paragraph (the one before the note), and replaces the word 'failure'
(a very wide category) with 'error' (implying ERRORs raised by SQL
commands inside a transaction block).

I think the following intends to convey that if a transaction block is
in an aborted state due to an error, the COMMIT command will behave
identical to the ROLLBACK command. So the reference to 'changes' is
extraneous, since a transaction block may have encountered error even
without having made any changes.

+   If no changes have been made - because the transaction is in an
+   aborted state - the effect of the commit will look like a rollback,
+   including the command tag output.

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.

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 ...

Best regards,
Gurjeet
http://Gurje.et