Re: New docs chapter on Transaction Management and related changes

On Mon, Nov 21, 2022 at 11:15:36AM +0100, Laurenz Albe wrote:
> > --- 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 ...

Yes, I like that, changed.

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

Uh, I thought you wanted "unaborted", but I now changed it to "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>

I used your wording, but technically you can use BEGIN/COMMIT with a
single statement, so multi-statement it not a requirement, so I used
your text but removed "Multi-statement":

Transactions can be created explicitly using <command>BEGIN</command> or
<command>START TRANSACTION</command> and ended using
<command>COMMIT</command> or <command>ROLLBACK</command>.

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

Agreed, changed. Updated patch attached.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson