Re: New docs chapter on Transaction Management and related changes - Mailing list pgsql-hackers

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