Date: Tue, 6 Sep 2022 15:33:21 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: Simon Riggs <simon.riggs@enterprisedb.com>
Cc: pgsql-hackers@postgresql.org
Subject: Re: New docs chapter on Transaction Management and related changes
Message-ID: <20220906203320.GT31833@telsasoft.com>
References: 
 <CANbhV-E_iy9fmrErxrCh8TZTyenpfo72Hf_XD2HLDppva4dUNA@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CANbhV-E_iy9fmrErxrCh8TZTyenpfo72Hf_XD2HLDppva4dUNA@mail.gmail.com>
User-Agent: Mutt/1.9.4 (2018-02-28)
Archived-At: 
 <https://www.postgresql.org/message-id/20220906203320.GT31833%40telsasoft.com>
Precedence: bulk

On Tue, Sep 06, 2022 at 04:16:02PM +0100, Simon Riggs wrote:
> New chapter on transaction management, plus a few related changes.
> 
> Markup and links are not polished yet, so please comment initially on
> the topics, descriptions and wording.

This is useful.  Nitpicks follow.


+        If executed in a subtransaction this will return the top-level xid.

I'd prefer it with a comma after "subtransaction"

+SQL Standard. PostgreSQL supports SAVEPOINTs through the implementation
+defined mechanism of subtransactions, which offer a superset of the required

implementation-defined

+features. Prepared transactions allow PostgreSQL to implement what SQL

what *the

+<para>
+All transactions are identified by a unique VirtualTransactionId (virtualxid or
+vxid), e.g. 4/12532, which is comprised of the BackendId (in this example, 4)
+and a sequentially assigned number unique to that backend, known as LocalXid

sequentially-assigned

+<para>
+If a transaction attempts to write to the database it will be assigned a

database comma

+property is used by the transaction system to say that if one xid is earlier
+than another xid then the earlier transaction attempted to write before the

xid comma then

+<para>
+Currently executing transactions are shown in the pg_locks view in columns

currently-executing

+"virtualxid" (text) and "transactionid" (xid), if an xid has been assigned.

maybe remove the "if assigned" part, since it's described next?

+Read transactions will have a virtualxid but a NULL xid, while write
+transactions will have both a virtualxid and an xid assigned.
+</para>

+<para>
+Row-level read locks may require the assignment of a multixact ID (mxid), which
+are recorded in the pg_multixact directory.

which *is ?

+top-level transaction. Subtransactions can also be started from other
+subtransactions. As a result, the arrangement of transaction and subtransactions

transactions (plural) ?

+form a hierarchy or tree. Thus, each subtransaction has one parent transaction.

+At present in PostgreSQL, only one transaction or subtransaction can be active at
+one time.

one time per command/query/request.

+Subtransactions may end via a commit or abort without affecting their parent

may end either by committing or aborting, without ..

+transaction, allowing the parent transaction to continue.

+also be started in other ways, such as PL/pgSQL's EXCEPTION clause. PL/Python and
+PL/TCL also support explicit subtransactions. Working with C API, users may also
+call BeginInternalSubTransaction().

*the C API ?

+If a subtransaction is assigned an xid, we refer to this as a subxid. Read-only
+subtransactions are not assigned a subxid, but when a subtransaction attempts to
+write it will be assigned a subxid. We ensure that all of a subxid's parents, up

write comma.
Or say: "subxid is not assigned until the subtransaction attempts to
write" ?

+<para>
+The more subtransactions each transaction uses, the greater the overhead for
+transaction management. Up to 64 subxids are cached in shmem for each backend,

backend semicolon

+Those commands are extensions to the SQL Standard, since the SQL syntax is not yet
+yet part of the standard, though the Standard does refer to encompassing

yet yet

+Information relating to these is stored in pg_twophase. Currently prepared

s/these/two-phase commits/

+transactions can be inspected using pg_prepared_xacts view.
+</para>

currently-prepared ?