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.

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 39be6243cac0ad6ba08fc3f807f4562074b946f1..b904238800a5b1d54a52c2278e8263bf259b91a8 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1570,7 +1570,11 @@ SET ENABLE_SEQSCAN TO OFF;
        
         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 , or to achieve best
+        performance.
         The open_* options also use O_DIRECT if available.
         The utility 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 8a118cfece8a191b57e86ddc68de79ebc719db17..70fc832e23d8f11d844dca34974b9502fc3168e0 100644 (file)
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -85,7 +85,9 @@
    by unchecking My Computer\Open\{select disk
    drive}\Properties\Hardware\Properties\Policies\Enable write caching on
    the disk.  Also on Windows, fsync and
-   fsync_writethrough never do write caching.
+   fsync_writethrough never do write caching.  The
+   fsync_writethrough option can also be used to disable
+   write caching on MacOS X.
   
 
   
@@ -529,8 +531,10 @@
    The  parameter determines how
    PostgreSQL will ask the kernel to force
     WAL 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 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 fsync
    has been turned off.
   
@@ -590,6 +594,7 @@
    irrecoverable data corruption.  Administrators should try to ensure
    that disks holding PostgreSQL's
    WAL log files do not make such false reports.
+   (See .)