Clean up Streaming Replication documentation a little bit. A lot more

needs to be done, but it's a step forward..

doc/src/sgml/high-availability.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.40 2010/02/09 16:50:25 heikki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.41 2010/02/12 08:28:44 heikki Exp $ -->
 
 <chapter id="high-availability">
  <title>High Availability, Load Balancing, and Replication</title>
@@ -764,7 +764,7 @@ if (!triggered)
    <para>
     <productname>PostgreSQL</> includes a simple streaming replication
     mechanism, which lets the standby server to stay more up-to-date than
-    file-based replication allows. The standby connects to the primary
+    file-based log shipping allows. The standby connects to the primary
     and the primary starts streaming WAL records from where the standby
     left off, and continues streaming them as they are generated, without
     waiting for the WAL file to be filled. So with streaming replication,
@@ -805,20 +805,17 @@ if (!triggered)
 
      <listitem>
       <para>
-       Set up connections and authentication so that the standby server can
+       Set <xref linkend="guc-listen-addresses"> and authentication options
-       successfully connect to the pseudo <literal>replication</> database of
+       (see <filename>pg_hba.conf</>) so that the standby server can connect to
-       the primary server (see
+       the pseudo <literal>replication</> database of the primary server (see
-       <xref linkend="streaming-replication-authentication">). Ensure that
+       <xref linkend="streaming-replication-authentication">).
-       <xref linkend="guc-listen-addresses"> and <filename>pg_hba.conf</> are
-       configured appropriately on the primary.
       </para>
       <para>
        On systems that support the keepalive socket option, setting
        <xref linkend="guc-tcp-keepalives-idle">,
        <xref linkend="guc-tcp-keepalives-interval"> and
-       <xref linkend="guc-tcp-keepalives-count"> helps you to find the
+       <xref linkend="guc-tcp-keepalives-count"> helps the master to notice
-       troubles with replication (e.g., the network outage or the failure of
+       a broken connection promptly.
-       the standby server) as soon as possible.
       </para>
      </listitem>
      <listitem>
@@ -827,13 +824,6 @@ if (!triggered)
        (see <xref linkend="guc-max-wal-senders"> for details).
       </para>
      </listitem>
-     <listitem>
-      <para>
-       Enable WAL archiving in the primary server because we need to make a base
-       backup of it later (see <xref linkend="guc-archive-mode"> and
-       <xref linkend="guc-archive-command"> for details).
-      </para>
-     </listitem>
      <listitem>
       <para>
        Start the <productname>PostgreSQL</> server on the primary.
@@ -850,13 +840,12 @@ if (!triggered)
      </listitem>
      <listitem>
       <para>
-       Set up WAL archiving, connections and authentication like the primary
+       If you're setting up the standby server for high availability purposes,
-       server, because the standby server might work as a primary server after
+       set up WAL archiving, connections and authentication like the primary
-       failover. Ensure that your settings are consistent with the
+       server, because the standby server will work as a primary server after
-       <emphasis>future</> environment after the primary and the standby
+       failover. If you're setting up the standby server for e.g reporting
-       server are interchanged by failover. If you're setting up the standby
+       purposes, with no plans to fail over to it, configure the standby
-       server for e.g reporting purposes, with no plans to fail over to it,
+       accordingly.
-       configure the standby accordingly.
       </para>
      </listitem>
      <listitem>
@@ -871,12 +860,25 @@ if (!triggered)
         <listitem>
          <para>
           Specifies whether to start the <productname>PostgreSQL</> server as
-          a standby. If this parameter is <literal>on</>, the streaming
+          a standby. If this parameter is <literal>on</>, the server will
-          replication is enabled and the standby server will try to connect
+          not end recovery when the end of archived WAL is reached, but
-          to the primary to receive and apply WAL records continuously. The
+          will keep trying to continue recovery using <varname>restore_command</>
-          default is <literal>off</>, which allows only an archive recovery
+          and by connecting to the primary server as specified by
-          without replication. So, streaming replication requires this
+          <varname>primary_conninfo</> setting.
-          parameter to be explicitly set to <literal>on</>.
+         </para>
+        </listitem>
+       </varlistentry>
+       <varlistentry>
+        <term><varname>restore_command</varname> (<type>string</type>)</term>
+        <term><varname>restore_end_command</varname> (<type>string</type>)</term>
+        <listitem>
+         <para>
+	  In standby-mode, <varname>restore_command</> (and <varname>restore_end_command</>) is set to a
+	  simple command or script like in PITR. pg_standby or similar tools
+	  that wait for the next WAL file to arrive, cannot be used with
+          streaming replication, as the server handles retries and waiting
+          itself. Set <varname>restore_command</> as you would if you were
+          recovering using a Continuous archiving backup (see <xref linkend="backup-pitr-recovery">).
          </para>
         </listitem>
        </varlistentry>
@@ -902,16 +904,22 @@ if (!triggered)
           the password needs to be set if the primary demands password
           authentication.
          </para>
+         <para>
+          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
+         </para>
         </listitem>
        </varlistentry>
        <varlistentry id="trigger-file" xreflabel="trigger_file">
         <term><varname>trigger_file</varname> (<type>string</type>)</term>
         <listitem>
          <para>
-          Specifies a trigger file whose presence activates the standby.
+          Specifies a trigger file whose presence ends recovery in the
-          If no trigger file is specified, the standby never exits
+          standby. If no trigger file is specified, the standby never exits
           recovery.
          </para>
+         <para>
+          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
+         </para>
         </listitem>
        </varlistentry>
       </variablelist>