From 136dd36dd2604daf0f7402e4fcd280415f61f005 Mon Sep 17 00:00:00 2001
From: Thomas Munro <thomas.munro@gmail.com>
Date: Fri, 26 Aug 2022 16:05:59 +1200
Subject: [PATCH 3/3] Doc: Corrections to claims about wal_sync_method.

We claimed that fsync_writethrough called fsync() and then flushed write
caches, but that is untrue.  Describe the actual system call, and
mention that it's macOS-only.

We claimed that all the wal_sync_method values were equally reliable,
except that fsync_writethrough might flush write caches.  In fact
open_[data]sync might differ from f[data]sync on several systems in
terms of power loss risk, depending on whether the filesystem tries to
use FUA, whether the driver passes it on, and whether the device honors
it.  That's too technical a topic to go into here, but let's remove the
misleading statement.

We talked about "preventing caching" when we meant "flushing caches".

We said that open_[data]sync would get you O_DIRECT where available, but
that is not generally true.  It is true only with wal_level=minimal and
max_wal_senders=0, which must surely be a very rare configuration.
---
 doc/src/sgml/config.sgml |  3 +--
 doc/src/sgml/wal.sgml    | 10 ++++------
 2 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index a5cd4e44c7..eac0a1c8fe 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3061,7 +3061,7 @@ include_dir 'conf.d'
         </listitem>
         <listitem>
         <para>
-         <literal>fsync_writethrough</literal> (call <function>fsync()</function> at each commit, forcing write-through of any disk write cache)
+         <literal>fsync_writethrough</literal> (macOS only: call <function>fcntl(F_FULLSYNC)</function> at each commit, flushing any disk write cache)
         </para>
         </listitem>
         <listitem>
@@ -3071,7 +3071,6 @@ include_dir 'conf.d'
         </listitem>
        </itemizedlist>
        <para>
-        The <literal>open_</literal>* options also use <literal>O_DIRECT</literal> if available.
         Not all of these choices are available on all platforms.
         The default is the first method in the above list that is supported
         by the platform, except that <literal>fdatasync</literal> is the default on
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 90cbacfe41..cf5f4c41d9 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -109,13 +109,13 @@
         by unchecking <literal>My Computer\Open\<replaceable>disk drive</replaceable>\Properties\Hardware\Properties\Policies\Enable write caching on the disk</literal>.
         Alternatively, set <varname>wal_sync_method</varname> to
         <literal>fdatasync</literal> (NTFS only) or <literal>fsync</literal>,
-        which prevent write caching.
+        which flush write caches.
       </para>
     </listitem>
 
     <listitem>
       <para>
-        On <productname>macOS</productname>, write caching can be prevented by
+        On <productname>macOS</productname>, write caches can be flushed by
         setting <varname>wal_sync_method</varname> to <literal>fsync_writethrough</literal>.
       </para>
     </listitem>
@@ -756,10 +756,8 @@
    The <xref linkend="guc-wal-sync-method"/> parameter determines how
    <productname>PostgreSQL</productname> will ask the kernel to force
    <acronym>WAL</acronym> updates out to disk.
-   All the options should be the same in terms of reliability, with
-   the exception of <literal>fsync_writethrough</literal>, which can sometimes
-   force a flush of the disk cache even when other options do not do so.
-   However, it's quite platform-specific which one will be the fastest.
+   It is platform-specific, and some cases also device-specific, which options
+   flush or write through volatile write caches.
    You can test the speeds of different options using the <xref
    linkend="pgtestfsync"/> program.
    Note that this parameter is irrelevant if <varname>fsync</varname>
-- 
2.35.1