Feedback-ID: ia2694551:Fastmail
Date: Fri, 14 Oct 2022 10:46:15 +0200
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Bruce Momjian <bruce@momjian.us>
Cc: Erik Rijkers <er@xs4all.nl>, Simon Riggs <simon.riggs@enterprisedb.com>,
	Robert Treat <rob@xzilla.net>, Justin Pryzby <pryzby@telsasoft.com>,
	PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: New docs chapter on Transaction Management and related changes
Message-ID: <20221014084615.chvollxv3oz43oqu@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <Y0iL7jzLfSbj1T38@momjian.us>
Archived-At: 
 <https://www.postgresql.org/message-id/20221014084615.chvollxv3oz43oqu%40alvherre.pgsql>
Precedence: bulk

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

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/
"Las cosas son buenas o malas segun las hace nuestra opinión" (Lisias)