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

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@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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