Re: New docs chapter on Transaction Management and related changes

On Sun, 11 Sept 2022 at 21:35, Robert Treat <rob(at)xzilla(dot)net> wrote:
>
> 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.

Thanks Robert. I've tried to accommodate all of your thoughts, plus Alvaro's.

New v5 attached.

Happy to receive further comments.

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