From 8c8d307f82976122980bbccf940319d1b8a71403 Mon Sep 17 00:00:00 2001 From: Etsuro Fujita Date: Fri, 13 May 2022 18:30:00 +0900 Subject: [PATCH] Doc: Improve description of the "parallel_commit" option for postgres_fdw. It wasn't very clear that if this option was enabled, postgres_fdw would commit remote transactions in parallel at main-transaction end, and commit remote subtransactions in parallel at subtransaction end, due to the references to (sub)transaction and other too specific documentation. Clarify that. Also reword to simplify. Follow-up for commit 04e706d42. Jonathan S. Katz, reviewed by Justin Pryzby, with some modifications by me. Discussion: https://postgr.es/m/1435bfd1-172b-de38-f590-4404a5a62eb0%40postgresql.org --- doc/src/sgml/postgres-fdw.sgml | 40 +++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml index b43d0aecba..68362fd160 100644 --- a/doc/src/sgml/postgres-fdw.sgml +++ b/doc/src/sgml/postgres-fdw.sgml @@ -460,10 +460,16 @@ OPTIONS (ADD password_required 'false'); Transaction Management Options - When multiple remote (sub)transactions are involved in a local - (sub)transaction, by default postgres_fdw commits - those remote (sub)transactions one by one when the local (sub)transaction - commits. + As described in the Transaction Management section, 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, by default + postgres_fdw commits those remote transactions + serially when the local transaction is committed. When multiple remote + subtransactions are involved in the current local subtransaction, by + default postgres_fdw commits those remote + subtransactions serially when the local subtransaction is committed. Performance can be improved with the following option: @@ -474,26 +480,24 @@ OPTIONS (ADD password_required 'false'); This option controls whether postgres_fdw 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 false. + 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 + false. - 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. - 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.