Re: New docs chapter on Transaction Management and related changes

On Fri, 14 Oct 2022 at 09:46, Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> 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.
>
> 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.
>
> > + <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?
>
> > + <para>
> > + Lock waits on table-level locks are shown waiting for
> > + <structfield>virtualxid</structfield>, while lock waits on row-level
> > + locks are shown waiting for <structfield>transactionid</structfield>.
> > + Row-level read and write locks are recorded directly in locked
> > + rows and can be inspected using the <xref linkend="pgrowlocks"/>
> > + extension. Row-level read locks might also require the assignment
> > + of multixact IDs (<literal>mxid</literal>). Mxids are recorded in
> > + the <filename>pg_multixact</filename> directory.
> > + </para>
>
> Hmm, ok.
>
> > + <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?

+1 to all of those suggestions

--
Simon Riggs http://www.EnterpriseDB.com/