Rename the parameter recovery_connections to hot_standby, to reduce possible

confusion with streaming-replication settings.  Also, change its default
value to "off", because of concern about executing new and poorly-tested
code during ordinary non-replicating operation.  Per discussion.

In passing do some minor editing of related documentation.

2 files changed, 64 insertions, 60 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 93c9ff183c2..c84529f267f 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.271 2010/04/28 16:10:39 heikki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.272 2010/04/29 21:36:18 tgl Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -1352,7 +1352,7 @@ SET ENABLE_SEQSCAN TO OFF;
     <sect2 id="runtime-config-wal-settings">
      <title>Settings</title>
      <variablelist>
-     
+
      <varlistentry id="guc-wal-level" xreflabel="wal_level">
       <term><varname>wal_level</varname> (<type>enum</type>)</term>
       <indexterm>
@@ -1362,7 +1362,7 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         <varname>wal_level</> determines how much information is written
         to the WAL. The default value is <literal>minimal</>, which writes
-        only minimal information needed to recover from a crash or immediate
+        only the information needed to recover from a crash or immediate
         shutdown. <literal>archive</> adds logging required for WAL archiving,
         and <literal>hot_standby</> further adds information required to run
         read-only queries on a standby server.
@@ -1385,8 +1385,8 @@ SET ENABLE_SEQSCAN TO OFF;
         the status of running transactions from the WAL. To enable read-only
         queries on a standby server, <varname>wal_level</> must be set to
         <literal>hot_standby</> on the primary. It is thought that there is
-        little measurable difference in performance from using
-        <literal>hot_standby</> level over <literal>archive</>, so feedback
+        little measurable difference in performance between using
+        <literal>hot_standby</> and <literal>archive</> levels, so feedback
         is welcome if any production impacts are noticeable.
        </para>
       </listitem>
@@ -1836,7 +1836,7 @@ SET ENABLE_SEQSCAN TO OFF;
        </para>
       </listitem>
      </varlistentry>
-     
+
      </variablelist>
     </sect2>
 
@@ -1860,8 +1860,7 @@ SET ENABLE_SEQSCAN TO OFF;
         servers (i.e., the maximum number of simultaneously running WAL sender
         processes). The default is zero. This parameter can only be set at
         server start. <varname>wal_level</> must be set to <literal>archive</>
-        or <literal>hot_standby</> to allow connections from standby
-        connections.
+        or <literal>hot_standby</> to allow connections from standby servers.
        </para>
        </listitem>
       </varlistentry>
@@ -1873,7 +1872,7 @@ SET ENABLE_SEQSCAN TO OFF;
        <listitem>
        <para>
         Specifies the delay between activity rounds for the WAL sender.
-        In each round the WAL sender sends any WAL accumulated since last
+        In each round the WAL sender sends any WAL accumulated since the last
         round to the standby server. It then sleeps for
         <varname>wal_sender_delay</> milliseconds, and repeats. The default
         value is 200 milliseconds (<literal>200ms</>).
@@ -1893,14 +1892,17 @@ SET ENABLE_SEQSCAN TO OFF;
        </indexterm>
        <listitem>
        <para>
-        Specifies the number of log file segments kept in <filename>pg_xlog</>
-        directory, in case a standby server needs to fetch them via streaming
+        Specifies the number of past log file segments kept in the
+        <filename>pg_xlog</>
+        directory, in case a standby server needs to fetch them for streaming
         replication. Each segment is normally 16 megabytes. If a standby
-        server connected to the primary falls behind more than
+        server connected to the primary falls behind by more than
         <varname>wal_keep_segments</> segments, the primary might remove
-        a WAL segment still needed by the standby and the replication
-        connection will be terminated.
+        a WAL segment still needed by the standby, in which case the
+        replication connection will be terminated.
+       </para>
 
+       <para>
         This sets only the minimum number of segments retained for standby
         purposes; the system might need to retain more segments for WAL
         archival or to recover from a checkpoint. If <varname>wal_keep_segments</>
@@ -1920,43 +1922,44 @@ SET ENABLE_SEQSCAN TO OFF;
 
     <variablelist>
 
-     <varlistentry id="recovery-connections" xreflabel="recovery_connections">
-      <term><varname>recovery_connections</varname> (<type>boolean</type>)</term>
+     <varlistentry id="guc-hot-standby" xreflabel="hot_standby">
+      <term><varname>hot_standby</varname> (<type>boolean</type>)</term>
       <indexterm>
-       <primary><varname>recovery_connections</> configuration parameter</primary>
+       <primary><varname>hot_standby</> configuration parameter</primary>
       </indexterm>
       <listitem>
        <para>
         Specifies whether or not you can connect and run queries during
-        recovery, for <xref linkend="hot-standby">. The default value is
-        <literal>on</literal>.
+        recovery, as described in <xref linkend="hot-standby">.
+        The default value is <literal>off</literal>.
         This parameter can only be set at server start. It only has effect
         during archive recovery or in standby mode.
        </para>
       </listitem>
      </varlistentry>
 
-     <varlistentry id="max-standby-delay" xreflabel="max_standby_delay">
-      <term><varname>max_standby_delay</varname> (<type>string</type>)</term>
+     <varlistentry id="guc-max-standby-delay" xreflabel="max_standby_delay">
+      <term><varname>max_standby_delay</varname> (<type>integer</type>)</term>
       <indexterm>
        <primary><varname>max_standby_delay</> configuration parameter</primary>
       </indexterm>
       <listitem>
        <para>
-        When server acts as a standby, this parameter specifies a wait policy
+        When Hot Standby is active, this parameter specifies a wait policy
         for applying WAL entries that conflict with active queries.
         If a conflict should occur the server will delay up to this number
         of seconds before it cancels conflicting queries, as
         described in <xref linkend="hot-standby-conflict">.
         Typically, this parameter is used only during replication.
+        The value is specified in seconds, and -1 causes the standby to wait
+        forever for a conflicting query to complete.
         The default is 30 seconds.
         This parameter can only be set in the <filename>postgresql.conf</>
         file or on the server command line.
        </para>
        <para>
-        A high value makes query cancel less likely, and -1
-        causes the standby to wait forever for a conflicting query to
-        complete.  Increasing this parameter might delay master server
+        A high value makes query cancel less likely.
+        Increasing this parameter or setting it to -1 might delay master server
         changes from appearing on the standby.
       </para>
       <para>
@@ -1966,7 +1969,7 @@ SET ENABLE_SEQSCAN TO OFF;
        query ends, there is a finite time required to apply backlogged
        WAL logs.  If a second long-running query appears before the
        WAL has caught up, the snapshot taken by the second query will
-       allow significantly less than <varname>max_standby_delay</>
+       allow significantly less than <varname>max_standby_delay</> seconds
        before query cancellation is possible.
       </para>
       </listitem>
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index da0d4d5de5f..b2f1a583fc3 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.64 2010/04/28 16:10:40 heikki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.65 2010/04/29 21:36:18 tgl Exp $ -->
 
 <chapter id="high-availability">
  <title>High Availability, Load Balancing, and Replication</title>
@@ -1127,7 +1127,8 @@ if (!triggered)
 
    <para>
     Hot Standby is the term used to describe the ability to connect to
-    the server and run queries while the server is in archive recovery. This
+    the server and run read-only queries while the server is in archive
+    recovery. This
     is useful for both log shipping replication and for restoring a backup
     to an exact state with great precision.
     The term Hot Standby also refers to the ability of the server to move
@@ -1137,7 +1138,7 @@ if (!triggered)
 
    <para>
     Running queries in recovery mode is similar to normal query operation,
-    though there are a several usage and administrative differences
+    though there are several usage and administrative differences
     noted below.
    </para>
 
@@ -1573,14 +1574,15 @@ if (!triggered)
    <title>Administrator's Overview</title>
 
    <para>
-    If there is a <filename>recovery.conf</> file present, the server will start
-    in Hot Standby mode by default, though <varname>recovery_connections</> can
-    be disabled via <filename>postgresql.conf</>. The server might take
-    some time to enable recovery connections since the server must first complete
+    If <varname>hot_standby</> is turned <literal>on</> in
+    <filename>postgresql.conf</> and there is a <filename>recovery.conf</>
+    file present, the server will run in Hot Standby mode.
+    However, it may take some time for Hot Standby connections to be allowed,
+    because the server will not accept connections until it has completed
     sufficient recovery to provide a consistent state against which queries
-    can run before enabling read only connections.  During this period,
+    can run.  During this period,
     clients that attempt to connect will be refused with an error message.
-    To confirm the server has come up, either loop retrying to connect from
+    To confirm the server has come up, either loop trying to connect from
     the application, or look for these messages in the server logs:
 
 <programlisting>
@@ -1592,12 +1594,11 @@ LOG:  consistent recovery state reached
 LOG:  database system is ready to accept read only connections
 </programlisting>
 
-    Consistency information is recorded once per checkpoint on the primary, as long
-    as <varname>wal_level</> is set to <literal>hot_standby</> on the primary.  It is not possible
-    to enable recovery connections on the standby when reading WAL written during the
-    period that <varname>wal_level</> was not set to <literal>hot_standby</> on the primary.
-    Reaching a consistent state can also be delayed in the presence
-    of both of these conditions:
+    Consistency information is recorded once per checkpoint on the primary.
+    It is not possible to enable hot standby when reading WAL
+    written during a period when <varname>wal_level</> was not set to
+    <literal>hot_standby</> on the primary.  Reaching a consistent state can
+    also be delayed in the presence of both of these conditions:
 
       <itemizedlist>
        <listitem>
@@ -1622,10 +1623,9 @@ LOG:  database system is ready to accept read only connections
     if they have been changed on the primary. For these parameters,
     the value on the standby must
     be equal to or greater than the value on the primary. If these parameters
-    are not set high enough then the standby will not be able to process
-    recovering transactions properly. If these values are set too low
-    the server will halt. Higher values can then be supplied and the server
-    restarted to begin recovery again.  The parameters are:
+    are not set high enough then the standby will refuse to start.
+    Higher values can then be supplied and the server
+    restarted to begin recovery again.  These parameters are:
 
       <itemizedlist>
        <listitem>
@@ -1648,7 +1648,8 @@ LOG:  database system is ready to accept read only connections
 
    <para>
     It is important that the administrator consider the appropriate setting
-    of <varname>max_standby_delay</>, set in <filename>postgresql.conf</>.
+    of <varname>max_standby_delay</>,
+    which can be set in <filename>postgresql.conf</>.
     There is no optimal setting, so it should be set according to business
     priorities. For example if the server is primarily tasked as a High
     Availability server, then you may wish to lower
@@ -1657,7 +1658,7 @@ LOG:  database system is ready to accept read only connections
     server for decision support queries then it might be acceptable to set this
     to a value of many hours (in seconds).  It is also possible to set
     <varname>max_standby_delay</> to -1 which means wait forever for queries
-    to complete, if there are conflicts; this will be useful when performing
+    to complete; this will be useful when performing
     an archive recovery from a backup.
    </para>
 
@@ -1668,10 +1669,8 @@ LOG:  database system is ready to accept read only connections
     all users are read-only; no changes occur to the data values
     themselves.  Users will still write large sort temporary files and
     re-generate relcache info files, so no part of the database
-    is truly read-only during hot standby mode. There is no restriction
-    on the use of set returning functions, or other users of
-    <function>tuplestore</>/<function>tuplesort</>
-    code. Note also that writes to remote databases will still be possible,
+    is truly read-only during hot standby mode.
+    Note also that writes to remote databases will still be possible,
     even though the transaction is read-only locally.
    </para>
 
@@ -1837,20 +1836,22 @@ LOG:  database system is ready to accept read only connections
    <title>Hot Standby Parameter Reference</title>
 
    <para>
-    Various parameters have been mentioned above in <xref linkend="hot-standby-admin">
+    Various parameters have been mentioned above in
+    <xref linkend="hot-standby-admin">
     and <xref linkend="hot-standby-conflict">.
    </para>
 
    <para>
-    On the primary, parameters <varname>wal_level</> and
-    <varname>vacuum_defer_cleanup_age</> can be used.
-    <varname>max_standby_delay</> has no effect if set on the primary.
+    On the primary, parameters <xref linkend="guc-wal-level"> and
+    <xref linkend="guc-vacuum-defer-cleanup-age"> can be used.
+    <xref linkend="guc-max-standby-delay"> has no effect if set on the primary.
    </para>
 
    <para>
-    On the standby, parameters <varname>recovery_connections</> and
-    <varname>max_standby_delay</> can be used.
-    <varname>vacuum_defer_cleanup_age</> has no effect during recovery.
+    On the standby, parameters <xref linkend="guc-hot-standby"> and
+    <xref linkend="guc-max-standby-delay"> can be used.
+    <xref linkend="guc-vacuum-defer-cleanup-age"> has no effect during
+    recovery.
    </para>
   </sect2>
 
@@ -1880,7 +1881,7 @@ LOG:  database system is ready to accept read only connections
    </listitem>
    <listitem>
     <para>
-     Valid starting points for recovery connections are generated at each
+     Valid starting points for standby queries are generated at each
      checkpoint on the master. If the standby is shut down while the master
      is in a shutdown state, it might not be possible to re-enter Hot Standby
      until the primary is started up, so that it generates further starting
@@ -1901,7 +1902,7 @@ LOG:  database system is ready to accept read only connections
      that normally take <literal>AccessExclusiveLocks</>, or you plan on having one
      large transaction that takes many <literal>AccessExclusiveLocks</>, you are
      advised to select a larger value of <varname>max_locks_per_transaction</>,
-     up to, but never more than twice the value of the parameter setting on
+     perhaps as much as twice the value of the parameter on
      the primary server. You need not consider this at all if
      your setting of <varname>max_prepared_transactions</> is <literal>0</>.
     </para>