Hi,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.
Attached is a patch to try to simplify the language for the description of the "parallel_commit" option. A few notes:
* 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. * I removed the "Be careful with this option" and instead clarified an explanation of the case that could cause performance impacts.
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! Jonathan[1] https://www.postgresql.org/docs/devel/postgres-fdw.html#id-1.11.7.47.11.7
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index b43d0aecba..23743435e0 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -460,11 +460,11 @@ 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.
- 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:
</para>
<variablelist>
@@ -473,27 +473,25 @@ OPTIONS (ADD password_required 'false');
<term><literal>parallel_commit</literal> (<type>boolean</type>)</term>
<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>.
+ This option controls whether <filename>postgres_fdw</filename> commits
in
+ parallel remote transactions opened on a foreign server in a local
+ transaction when the local transaction is committed. This setting
+ applies to remote and local substransactions. 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 have 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
