Re: postgres_fdw "parallel_commit" docs

[Jonathan S. Katz]

Hi Etsuro,

On 5/12/22 7:26 AM, Etsuro Fujita wrote:

I modified the patch to use the old language.  Also, I fixed a typo
reported by Justin.

Attached is an updated patch.  I'll commit the patch if no objections.

Thanks for reviewing and revising! I think this is much easier to read.

I made a few minor copy edits. Please see attached.

Thanks,

Jonathan

diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index b43d0aecba..e35ae4ff72 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -460,10 +460,16 @@ OPTIONS (ADD password_required 'false');
    <title>Transaction Management Options</title>
 
    <para>
-    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.
+    As described in the Transaction Management section, in
+    <filename>postgres_fdw</filename> 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, by default
+    <filename>postgres_fdw</filename> commits those remote transactions
+    serially when the local transaction is committed. When
+    multiple remote subtransactions are involved in the current local
+    subtransaction, by default <filename>postgres_fdw</filename> commits those
+    remote subtransactions serially when the local subtransaction is committed.
     Performance can be improved with the following option:
    </para>
 
@@ -474,26 +480,24 @@ OPTIONS (ADD password_required 'false');
      <listitem>
       <para>
        This option controls whether <filename>postgres_fdw</filename> commits
-       remote (sub)transactions opened on a foreign server in a local
-       (sub)transaction in parallel when the local (sub)transaction commits.
-       This option can only be specified for foreign servers, not per-table.
-       The default is <literal>false</literal>.
+       in parallel remote transactions opened on a foreign server in a local
+       transaction when the local transaction is committed. This setting also
+       applies to remote and local subtransactions. This option can only be
+       specified for foreign servers, not per-table. The default is
+       <literal>false</literal>.
       </para>
 
       <para>
-       If multiple foreign servers with this option enabled are involved in
-       a local (sub)transaction, multiple remote (sub)transactions opened on
-       those foreign servers in the local (sub)transaction are committed in
-       parallel across those foreign servers when the local (sub)transaction
-       commits.
+       If multiple foreign servers with this option enabled are involved in a
+       local transaction, multiple remote transactions on those foreign
+       servers are committed in parallel across those foreign servers when
+       the local transaction is committed.
       </para>
 
       <para>
-       For a foreign server with this option enabled, if many remote
-       (sub)transactions are opened on the foreign server in a local
-       (sub)transaction, this option might increase the remote server's load
-       when the local (sub)transaction commits, so be careful when using this
-       option.
+       When this option is enabled, a foreign server with many remote
+       transactions may see a negative performance impact when the local
+       transaction is committed.
       </para>
      </listitem>
     </varlistentry>

OpenPGP_signature
Description: OpenPGP digital signature