Reword fsync and full_page_writes docs to be clearer about when to turn

them off.

Josh Berkus, with slight wording changes by me.

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index faf858f04c98bb67778e037b5b1922e99ba0bdae..3c499b134cf3d253fcc6bfeb6303433d25959145 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-
+
 
 
   Server Configuration
@@ -1413,34 +1413,23 @@ SET ENABLE_SEQSCAN TO OFF;
        
 
        
-        However, using fsync results in a
-        performance penalty: when a transaction is committed,
-        PostgreSQL must wait for the
-        operating system to flush the write-ahead log to disk.  When
-        fsync is disabled, the operating system is
-        allowed to do its best in buffering, ordering, and delaying
-        writes. This can result in significantly improved performance.
-        However, if the system crashes, the results of the last few
-        committed transactions might be completely lost, or worse,
-        might appear partially committed, leaving the database in an
-        inconsistent state. In the
-        worst case, unrecoverable data corruption might occur.
-        (Crashes of the database software itself are not
-        a risk factor here.  Only an operating-system-level crash
-        creates a risk of corruption.)
+        While turning off fsync is often a performance
+        benefit, this can result in unrecoverable data corruption in
+        the event of an unexpected system shutdown or crash.  Thus it
+        is only advisable to turn off  fsync if
+        you can easily recreate your entire database from external
+        data.
        
 
        
-        Due to the risks involved, there is no universally correct
-        setting for fsync. Some administrators
-        always disable fsync, while others only
-        turn it off during initial bulk data loads, where there is a clear
-        restart point if something goes wrong.  Others
-        always leave fsync enabled. The default is
-        to enable fsync, for maximum reliability.
-        If you trust your operating system, your hardware, and your
-        utility company (or your battery backup), you can consider
-        disabling fsync.
+        Examples of safe circumstances for turning off
+        fsync include the initial loading a new
+        database cluster from a backup file, using a database cluster
+        for processing statistics on an hourly basis which is then
+        recreated, or for a reporting read-only database clone which
+        gets recreated frequently and is not used for failover.  High
+        quality hardware alone is not a sufficient justification for
+        turning off fsync.
        
 
        
@@ -1572,12 +1561,10 @@ SET ENABLE_SEQSCAN TO OFF;
 
        
         Turning this parameter off speeds normal operation, but
-        might lead to a corrupt database after an operating system crash
-        or power failure. The risks are similar to turning off
-        fsync, though smaller.  It might be safe to turn off
-        this parameter if you have hardware (such as a battery-backed disk
-        controller) or file-system software that reduces
-        the risk of partial page writes to an acceptably low level (e.g., ZFS).
+        might lead to either unrecoverable data corruption, or silent
+        data corruption, after a system failure. The risks are similar to turning off
+        fsync, though smaller, and it should be turned off
+        only based on the same circumstances recommended for that parameter.