Re: New docs chapter on Transaction Management and related changes

On Fri, 2022-11-18 at 14:28 -0500, Bruce Momjian wrote:
> New patch attached.

Thanks.

> --- a/doc/src/sgml/ref/release_savepoint.sgml
> +++ b/doc/src/sgml/ref/release_savepoint.sgml

> + <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, excluding rolled back savepoints changes, 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.

I am not sure if "rolled back savepoints changes" is clear enough.
I understand that you are trying to avoid the term "subtransaction".
How about:

All changes made since the creation of the savepoint that didn't already
get rolled back are merged ...

> --- a/doc/src/sgml/ref/rollback.sgml
> +++ b/doc/src/sgml/ref/rollback.sgml
>
> + If <literal>AND CHAIN</literal> is specified, a new (unaborted)

*Sigh* I'll make one last plea for "not aborted".

> --- /dev/null
> +++ b/doc/src/sgml/xact.sgml

> + <para>
> + Transactions can be created explicitly using <command>BEGIN</command>
> + and <command>COMMIT</command>, which creates a transaction block.
> + An SQL statement outside of a transaction block automatically uses
> + a single-statement transaction.
> + </para>

Sorry, I should have noted that the first time around.

Transactions are not created using COMMIT.

Perhaps we should also avoid the term "transaction block". Even without speaking
of a "block", way too many people confuse PL/pgSQL's BEGIN ... END blocks
with transactions. On the other hand, we use "transaction block" everywhere
else in the documentation...

How about:

<para>
Multi-statement transactions can be created explicitly using
<command>BEGIN</command> or <command>START TRANSACTION</command> and
are ended using <command>COMMIT</command> or <command>ROLLBACK</command>.
An SQL statement outside of a transaction block automatically uses
a single-statement transaction.
</para>

> + <sect1 id="xact-locking">
> +
> + <title>Transactions and Locking</title>
> +
> + <para>
> + The transaction IDs of currently executing transactions are shown in
> + <link linkend="view-pg-locks"><structname>pg_locks</structname></link>
> + in columns <structfield>virtualxid</structfield> and
> + <structfield>transactionid</structfield>. Read-only transactions
> + will have <structfield>virtualxid</structfield>s but NULL
> + <structfield>transactionid</structfield>s, while read-write transactions
> + will have both as non-NULL.
> + </para>

Perhaps the following will be prettier than "have both as non-NULL":

..., while both columns will be set in read-write transactions.

Yours,
Laurenz Albe