Improve WAL reliability documentation, and add more cross-references to it.

In particular, we are now more explicit about the fact that you may need
wal_sync_method=fsync_writethrough for crash-safety on some platforms,
including MaxOS X.  There's also now an explicit caution against assuming
that the default setting of wal_sync_method is either crash-safe or best
for performance.

2 files changed, 13 insertions, 4 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index affce37d0d2..87d182c4c45 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1570,7 +1570,11 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         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.
+        by the platform.  The default is not necessarily best; it may be
+        necessary to change this setting, or other aspects of your system
+        configuration, in order to create a crash-safe configuration, as
+        discussed in <xref linkend="wal-reliability">, or to achieve best
+        performance.
         The <literal>open_</>* options also use <literal>O_DIRECT</> if available.
         The utility <filename>src/tools/fsync</> in the PostgreSQL source tree
         can do performance testing of various fsync methods.
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 6730c9328ed..2726acb8a7e 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -85,7 +85,9 @@
    by unchecking <literal>My Computer\Open\{select disk
    drive}\Properties\Hardware\Properties\Policies\Enable write caching on
    the disk</>.  Also on Windows, <literal>fsync</> and
-   <literal>fsync_writethrough</> never do write caching.
+   <literal>fsync_writethrough</> never do write caching.  The
+   <literal>fsync_writethrough</> option can also be used to disable
+   write caching on <productname>MacOS X</>.
   </para>
 
   <para>
@@ -529,8 +531,10 @@
    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,
-   but it's quite platform-specific which one will be the fastest.
+   With the exception of <literal>fsync_writethrough</>, which can sometimes
+   force a flush of the disk cache even when other options do not do so,
+   all the options should be the same in terms of reliability.
+   However, it's quite platform-specific which one will be the fastest.
    Note that this parameter is irrelevant if <varname>fsync</varname>
    has been turned off.
   </para>
@@ -590,6 +594,7 @@
    irrecoverable data corruption.  Administrators should try to ensure
    that disks holding <productname>PostgreSQL</productname>'s
    <acronym>WAL</acronym> log files do not make such false reports.
+   (See <xref linkend="wal-reliability">.)
   </para>
 
   <para>