From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Bruce Momjian <bruce@momjian.us>
Cc: Erik Rijkers <er@xs4all.nl>
Cc: Simon Riggs <simon.riggs@enterprisedb.com>
Cc: Robert Treat <rob@xzilla.net>
Cc: Justin Pryzby <pryzby@telsasoft.com>
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: New docs chapter on Transaction Management and related changes
Date: Fri, 14 Oct 2022 10:46:15 +0200
Message-ID: <20221014084615.chvollxv3oz43oqu@alvherre.pgsql> (raw)
In-Reply-To: <Y0iL7jzLfSbj1T38@momjian.us>
+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)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: alvherre@alvh.no-ip.org, bruce@momjian.us, er@xs4all.nl, simon.riggs@enterprisedb.com, rob@xzilla.net, pryzby@telsasoft.com
Subject: Re: New docs chapter on Transaction Management and related changes
In-Reply-To: <20221014084615.chvollxv3oz43oqu@alvherre.pgsql>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox