On Sun, 11 Sept 2022 at 21:35, Robert Treat <r...@xzilla.net> wrote: > > On Wed, Sep 7, 2022 at 8:05 AM Simon Riggs <simon.ri...@enterprisedb.com> > wrote: > > > > On Tue, 6 Sept 2022 at 21:33, Justin Pryzby <pry...@telsasoft.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/
xact_docs.v5.patch
Description: Binary data
