Re: New docs chapter on Transaction Management and related changes

On Fri, Oct 14, 2022 at 10:46:15AM +0200, Álvaro Herrera wrote:
> +1 for this new chapter. This latest patch looks pretty good. I think
> that introducing the concept of "sub-commit" as in Simon's follow-up
> patch clarifies things, though the word itself looks very odd. Maybe
> it's okay. The addition of the savepoint example looks good also.

Yes, I like that term since it isn't a permament commit.

> On 2022-Oct-13, Bruce Momjian wrote:
>
> > + <para>
> > + <productname>PostgreSQL</productname> supports a two-phase commit (2PC)
> > + protocol that allows multiple distributed systems to work together
> > + in a transactional manner. The commands are <command>PREPARE
> > + TRANSACTION</command>, <command>COMMIT PREPARED</command> and
>
> I suggest/request that we try to avoid breaking tagged constants in
> DocBook; doing so makes it much easier to miss them later when grepping
> for them (don't laugh, it has happened to me). Also, it breaks
> formatting in some weird cases. I know this makes editing a bit harder
> because you can't just reflow with your editor like you would normal
> text. So this'd be:
>
> + in a transactional manner. The commands are <command>PREPARE TRANSACTION</command>,
> + <command>COMMIT PREPARED</command> and
>
> with whatever word wrapping you like, except breaking between PREPARE
> and TRANSACTION.

Uh, I do a lot of word wraps and I don't think I can reaonably avoid
these splits.

>
> > + <para>
> > + In addition to <literal>vxid</literal> and <type>xid</type>,
> > + when a transaction is prepared it is also identified by a Global
> > + Transaction Identifier (<acronym>GID</acronym>). GIDs
> > + are string literals up to 200 bytes long, which must be
> > + unique amongst other currently prepared transactions.
> > + The mapping of GID to xid is shown in <link
> > + linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link>.
> > + </para>
>
> Maybe say "is prepared for two-phase commit", to make the topic of this
> paragraph more obvious?

Agreed.

> > + <para>
> > + The parent xid of each subxid is recorded in the
> > + <filename>pg_subtrans</filename> directory. No entry is made for
> > + top-level xids since they do not have a parent, nor is an entry made
> > + for read-only subtransactions.
> > + </para>
>
> Maybe say "the immediate parent xid of each ...", or is it too obvious?

Agreed with your wording.

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

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