Re: postgres_fdw "parallel_commit" docs

Hi Jonathan,

On Tue, May 10, 2022 at 12:37 AM Jonathan S. Katz <jkatz@postgresql.org> wrote:
> While researching PG15 features, I was trying to read through the
> docs[1] for the "parallel_commit" (04e706d4) feature in postgres_fdw to
> better understand what it does. I found myself becoming lost with the
> references to (sub)transaction and a few other items that, while
> accurate, may be overly specific in this context.

I have to admit that that is making the docs confusing.

> Attached is a patch to try to simplify the language for the description
> of the "parallel_commit" option. A few notes:

Thanks for the patch!

> * I stated that this feature applies to both transactions and
> subtransactions.
> * I tried to condense some of the language around remote/local
> transactions. If this makes the statement inaccurate, let's revise.

One thing I noticed is this bit:

-    When multiple remote (sub)transactions are involved in a local
-    (sub)transaction, by default <filename>postgres_fdw</filename> commits
-    those remote (sub)transactions one by one when the local (sub)transaction
-    commits.
-    Performance can be improved with the following option:
+    When multiple remote transactions or subtransactions are involved in a
+    local transaction (or subtransaction) on a foreign server,
+    <filename>postgres_fdw</filename> by default commits those remote
+    transactions serially when the local transaction commits.
Performance can be
+    improved with the following option:

I think this might still be a bit confusing.  How about rewriting it
to something like  this?

As described in F.38.4. Transaction Management, in postgres_fdw
transactions are managed by creating corresponding remote
transactions, and subtransactions are managed by creating
corresponding remote subtransactions.  When multiple remote
transactions are involved in the current local transaction,
postgres_fdw by default commits those remote transactions serially
when the local transaction is committed.  When multiple remote
subtransactions are involved in the current local subtransaction, it
by default commits those remote subtransactions serially when the
local subtransaction is committed.  Performance can be improved with
the following option:

It might be a bit redundant to explain the transaction/subtransaction
cases differently, but I think it makes it clear and maybe
easy-to-understand that how they are handled by postgres_fdw by
default.

> * I removed the "Be careful with this option" and instead clarified an
> explanation of the case that could cause performance impacts.

I like this change.

> This feature seems like it will be impactful for distributed workloads
> using "postgres_fdw" so I want to ensure that we both accurately and
> clearly capture what it can do.

Thanks!

Best regards,
Etsuro Fujita