Fix erroneous documentation of synchronous_commit = remote_write.

tglsfdc · tglsfdc · commit 9e8f8ef1f072 · 2012-08-22T14:04:49.000-04:00
The docs claimed that this mode only waits for the standby to receive WAL
data, but actually it waits for the data to be written out to the standby's
OS; which is a pretty significant difference because it removes the risk of
crash of the walreceiver process.
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -1649,8 +1649,9 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         Specifies whether transaction commit will wait for WAL records
         to be written to disk before the command returns a <quote>success</>
-        indication to the client.  Valid values are <literal>on</>, <literal>remote_write</>,
-        <literal>local</>, and <literal>off</>.  The default, and safe, value
+        indication to the client.  Valid values are <literal>on</>,
+        <literal>remote_write</>, <literal>local</>, and <literal>off</>.
+        The default, and safe, setting
         is <literal>on</>.  When <literal>off</>, there can be a delay between
         when success is reported to the client and when the transaction is
         really guaranteed to be safe against a server crash.  (The maximum
@@ -1667,27 +1668,34 @@ SET ENABLE_SEQSCAN TO OFF;
        </para>
        <para>
         If <xref linkend="guc-synchronous-standby-names"> is set, this
-        parameter also controls whether or not transaction commit will wait
-        for the transaction's WAL records to be flushed to disk and replicated
-        to the standby server.  When <literal>remote_write</>, the commit wait will
-        last until a reply from the current synchronous standby indicates
-        it has received the commit record of the transaction to memory.
-        Normally this causes no data loss at the time of failover. However,
-        if both primary and standby crash, and the database cluster of
-        the primary gets corrupted, recent committed transactions might
-        be lost. When <literal>on</>,  the commit wait will last until a reply
-        from the current synchronous standby indicates it has flushed
-        the commit record of the transaction to durable storage. This
-        avoids any data loss unless the database cluster of both primary and
-        standby gets corrupted simultaneously. If synchronous
+        parameter also controls whether or not transaction commits will wait
+        for the transaction's WAL records to be replicated to the standby
+        server.
+        When set to <literal>on</>, commits will wait until a reply
+        from the current synchronous standby indicates it has received
+        the commit record of the transaction and flushed it to disk.  This
+        ensures the transaction will not be lost unless both primary and
+        standby suffer corruption of their database storage.
+        When set to <literal>remote_write</>, commits will wait
+        until a reply from the current synchronous standby indicates it has
+        received the commit record of the transaction and written it out to
+        the standby's operating system, but the data has not necessarily
+        reached stable storage on the standby. This setting is sufficient to
+        ensure data preservation even if the standby instance of
+        <productname>PostgreSQL</> were to crash, but not if the standby
+        suffers an operating-system-level crash.
+       </para>
+       <para>
+        When synchronous
         replication is in use, it will normally be sensible either to wait
-        for both local flush and replication of WAL records, or
+        for both local flush to disk and replication of WAL records, or
         to allow the transaction to commit asynchronously.  However, the
-        special value <literal>local</> is available for transactions that
+        setting <literal>local</> is available for transactions that
         wish to wait for local flush to disk, but not synchronous replication.
-        If <varname>synchronous_standby_names</> is not set, <literal>on</>,
-        <literal>remote_write</> and <literal>local</> provide the same
-        synchronization level; transaction commit only waits for local flush.
+        If <varname>synchronous_standby_names</> is not set, the settings
+        <literal>on</>, <literal>remote_write</> and <literal>local</> all
+        provide the same synchronization level: transaction commits only wait
+        for local flush to disk.
        </para>
        <para>
         This parameter can be changed at any time; the behavior for any
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
@@ -989,9 +989,9 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
     <xref linkend="runtime-config-replication-master">.)
     This configuration will cause each commit to wait for
     confirmation that the standby has written the commit record to durable
-    storage, even if that takes a very long time.
+    storage.
     <varname>synchronous_commit</> can be set by individual
-    users, so can be configured in the configuration file, for particular
+    users, so it can be configured in the configuration file, for particular
     users or databases, or dynamically by applications, in order to control
     the durability guarantee on a per-transaction basis.
    </para>
@@ -1015,10 +1015,14 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
    <para>
     Setting <varname>synchronous_commit</> to <literal>remote_write</> will
     cause each commit to wait for confirmation that the standby has received
-    the commit record to memory. This provides a lower level of durability
-    than <literal>on</> does. However, it's a practically useful setting
-    because it can decrease the response time for the transaction, and causes
-    no data loss unless both the primary and the standby crashes and
+    the commit record and written it out to its own operating system, but not
+    for the data to be flushed to disk on the standby.  This
+    setting provides a weaker guarantee of durability than <literal>on</>
+    does: the standby could lose the data in the event of an operating system
+    crash, though not a <productname>PostgreSQL</> crash.
+    However, it's a useful setting in practice
+    because it can decrease the response time for the transaction.
+    Data loss could only occur if both the primary and the standby crash and
     the database of the primary gets corrupted at the same time.
    </para>
 
