Re: New docs chapter on Transaction Management and related changes

On Wed, Sep 7, 2022 at 8:05 AM Simon Riggs <simon(dot)riggs(at)enterprisedb(dot)com> wrote:
>
> On Tue, 6 Sept 2022 at 21:33, Justin Pryzby <pryzby(at)telsasoft(dot)com> wrote:
> >
> > 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.
> >
> I've also added further notes about prepared transactions.
>
> I attach a diff against the original patch, plus a new clean copy.
>

Some feedback on the v4 patch, hopefully useful.

+<para>
+Transactions may be started explicitly using BEGIN and COMMIT
commands, known as
+a transaction block. A transaction will also be started and ended
implicitly for
+each request when outside of a transaction block.
+</para>

Transactions may be managed explicitly using BEGIN and COMMIT commands, known as
a transaction block.

+Committed subtransactions are recorded as committed if the main transaction
+commits. The word subtransaction is often abbreviated to "subxact".
+</para>

Committed subtransactions are only recorded as committed if the main
transaction commits,
otherwise any work done in a subtransaction will be rolled back or
aborted. The word subtransaction is
often abbreviated as "subxact".

+<para>
+Subtransactions may be started explicitly by using the SAVEPOINT
command, but may
+also be started in other ways, such as PL/pgSQL's EXCEPTION clause.
PL/Python and
+PL/TCL also support explicit subtransactions. Working with the C API, users may
+also call BeginInternalSubTransaction().
+</para>

I think this paragraph (or something similar) should be the opening
paragraph for this section, so that readers are immediately given
context for what PostgreSQL considers to be a subtransaction.

+prepared transactions that were prepared before the last checkpoint.
In the typical
+case, shorter-lived prepared transactions are stored only in shared
memory and WAL.
+Currently-prepared transactions can be inspected using the
pg_prepared_xacts view.
+</para>

Transactions that are currently prepared can be inspected using the
pg_prepated_xacts view.

* I thought the hyphenated wording looked odd, though I understand why
you used it. We don't use it elsewhere though (just `currently
prepared` san hyphen) so re-worded to match the other wording.

Robert Treat
https://xzilla.net