On Fri, Aug 14, 2020 at 01:32:35PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/runtime-config-wal.html
> Description:
>
> Hello,
>
> First of all I would like to say that PostgreSQL has the best documentation
> I've ever seen. It is very clear and comprehensive. That's the main reason
> why I decided to add my little 2 cents and make it even better.
>
> I think that the distinction between first three values of
> synchronous_commit parameter is not clear enough
> (https://www.postgresql.org/docs/12/runtime-config-wal.html#RUNTIME-CONFIG-WAL-SETTINGS).
>
> " When set to on, commits will wait until replies from the current
> synchronous standby(s) indicate they have received the commit record of the
> transaction and flushed it to disk. This ensures the transaction will not be
> lost unless both the primary and all synchronous standbys suffer corruption
> of their database storage. When set to remote_apply, commits will wait until
> replies from the current synchronous standby(s) indicate they have received
> the commit record of the transaction and applied it, so that it has become
> visible to queries on the standby(s). When set to remote_write, commits will
> wait until replies from the current synchronous standby(s) indicate they
> have received the commit record of the transaction and written it out to
> their operating system. This setting is sufficient to ensure data
> preservation even if a standby instance of PostgreSQL were to crash, but not
> if the standby suffers an operating-system-level crash, since the data has
> not necessarily reached stable storage on the standby"
>
> The last sentence : "This setting is sufficient to ensure data preservation
> even if a standby instance..." seems to refer only to the remote_write
> option while in my option it should refer to both remote_write and
> remote_apply options, as the fsync is performed only when synchronous_commit
> is set to ON.
>
> In other words I think that the documentation should be more clear in terms
> of which option uses fsync.
I think this paragraph just has just too complex. I have moved the
mention of remote_apply into its own paragraph, and simplified the
sentences about remote_write. Is this attached patch better?
--
Bruce Momjian <br...@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
new file mode 100644
index 7a7177c..e3940e5
*** a/doc/src/sgml/config.sgml
--- b/doc/src/sgml/config.sgml
*************** include_dir 'conf.d'
*** 2729,2752 ****
the commit record of the transaction and flushed it to disk. This
ensures the transaction will not be lost unless both the primary and
all synchronous standbys suffer corruption of their database storage.
- When set to <literal>remote_apply</literal>, commits will wait until replies
- from the current synchronous standby(s) indicate they have received the
- commit record of the transaction and applied it, so that it has become
- visible to queries on the standby(s).
When set to <literal>remote_write</literal>, commits will wait until replies
from the current synchronous standby(s) indicate they have
! received the commit record of the transaction and written it out to
! their operating system. This setting is sufficient to
! ensure data preservation even if a standby instance of
! <productname>PostgreSQL</productname> were to crash, but not if the standby
! suffers an operating-system-level crash, since the data has not
necessarily reached stable storage on the standby.
! Finally, the setting <literal>local</literal> causes commits to wait for
local flush to disk, but not for replication. This is not usually
desirable when synchronous replication is in use, but is provided for
completeness.
</para>
<para>
If <varname>synchronous_standby_names</varname> is empty, the settings
<literal>on</literal>, <literal>remote_apply</literal>, <literal>remote_write</literal>
and <literal>local</literal> all provide the same synchronization level:
--- 2729,2755 ----
the commit record of the transaction and flushed it to disk. This
ensures the transaction will not be lost unless both the primary and
all synchronous standbys suffer corruption of their database storage.
When set to <literal>remote_write</literal>, commits will wait until replies
from the current synchronous standby(s) indicate they have
! received the commit record of the transaction and written it to
! their file systems. This setting ensures data preservation if a standby instance of
! <productname>PostgreSQL</productname> crashes, but not if the standby
! suffers an operating-system-level crash because the data has not
necessarily reached stable storage on the standby.
! The setting <literal>local</literal> causes commits to wait for
local flush to disk, but not for replication. This is not usually
desirable when synchronous replication is in use, but is provided for
completeness.
</para>
<para>
+ Finally, when set to <literal>remote_apply</literal>, commits will
+ wait until replies from the current synchronous standby(s) indicate
+ they have received the commit record of the transaction and applied
+ it, so that it has become visible to queries on the standby(s).
+ This can cause much larger commit delays than previous settings
+ since it involves WAL replay.
+ </para>
+ <para>
If <varname>synchronous_standby_names</varname> is empty, the settings
<literal>on</literal>, <literal>remote_apply</literal>, <literal>remote_write</literal>
and <literal>local</literal> all provide the same synchronization level:
