Improve docs

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index d249959f205970c1b287ec5a9bdee59ffa4dfd8c..7c5b576b7152f2ef64880c14afb49303f07ef697 100644 (file)
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1272,7 +1272,9 @@ primary_slot_name = 'node_a_slot'
     and might stay down.  To return to normal operation, a standby server
     must be recreated,
     either on the former primary system when it comes up, or on a third,
-    possibly new, system. Once complete, the primary and standby can be
+    possibly new, system. The <application>pg_rewind</> utility can be
+    used to speed up this process on large clusters.
+    Once complete, the primary and standby can be
     considered to have switched roles. Some people choose to use a third
     server to provide backup for the new primary until the new standby
     server is recreated,

diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index b06b713c18382753be36693c56a3420d2625697d..9e1bca95591d1e1cc1c5da6921f58d6a0a0cef05 100644 (file)
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -1,10 +1,10 @@
 <!--
-doc/src/sgml/pg_rewind.sgml
+doc/src/sgml/ref/pg_rewind.sgml
 PostgreSQL documentation
 -->
 
-<refentry id="pgrewind">
- <indexterm zone="pgrewind">
+<refentry id="app-pgrewind">
+ <indexterm zone="app-pgrewind">
   <primary>pg_rewind</primary>
  </indexterm>
 
@@ -42,38 +42,53 @@ PostgreSQL documentation
 
   <para>
     <application>pg_rewind</> is a tool for synchronizing a PostgreSQL cluster
-    with another copy of the same cluster, after the cluster's timelines have
+    with another copy of the same cluster, after the clusters' timelines have
     diverged. A typical scenario is to bring an old master server back online
     after failover, as a standby that follows the new master.
   </para>
 
   <para>
     The result is equivalent to replacing the target data directory with the
-    source one. All files are copied, including configuration files. The advantage
-    of pg_rewind over restoring a base backup, or tools like rsync, is that
-    pg_rewind does not require reading through all unchanged files in the cluster.
-    That makes it a lot faster when the database is large and only a small portion
-    of it differs between the clusters.
+    source one. All files are copied, including configuration files. The
+    advantage of <application>pg_rewind</> over taking a new base backup, or
+    tools like <application>rsync</>, is that <application>pg_rewind</> does
+    not require reading through all unchanged files in the cluster. That makes
+    it a lot faster when the database is large and only a small portion of it
+    differs between the clusters.
   </para>
 
   <para>
-    pg_rewind examines the timeline histories of the source and target clusters
-    to determine the point where they diverged, and expects to find WAL in the
-    target cluster's pg_xlog directory reaching all the way back to the point of
-    divergence. In the typical failover scenario where the target cluster was shut
-    down soon after the divergence, that is not a problem, but if the target cluster
-    had run for a long time after the divergence, the old WAL files might not be
-    present anymore. In that case, they can be manually copied from the WAL archive
-    to the pg_xlog directory. Fetching missing files from a WAL archive automatically
-    is currently not supported.
+    <application>pg_rewind</> examines the timeline histories of the source
+    and target clusters to determine the point where they diverged, and
+    expects to find WAL in the target cluster's <filename>pg_xlog</> directory
+    reaching all the way back to the point of divergence. In the typical
+    failover scenario where the target cluster was shut down soon after the
+    divergence, that is not a problem, but if the target cluster had run for a
+    long time after the divergence, the old WAL files might not be present
+    anymore. In that case, they can be manually copied from the WAL archive to
+    the <filename>pg_xlog</> directory. Fetching missing files from a WAL
+    archive automatically is currently not supported.
   </para>
-</refsect1>
+
+  <para>
+    When the target server is started up for the first time after running
+    <application>pg_rewind</>, it will go into recovery mode and replay all
+    WAL generated in the source server after the point of divergence.
+    If some of the WAL was no longer available in the source server when
+    <application>pg_rewind</> was run, and thereforce could not be copied by
+    <application>pg_rewind</> session, it needs to be made available when the
+    target server is started up. That can be done by creating a
+    <filename>recovery.conf</> file in the target data directory with a
+    suitable <varname>restore_command</>.
+  </para>
+ </refsect1>
 
  <refsect1>
   <title>Options</title>
 
    <para>
-    <application>pg_rewind</application> accepts the following command-line arguments:
+    <application>pg_rewind</application> accepts the following command-line
+    arguments:
 
     <variablelist>
      <varlistentry>
@@ -81,9 +96,9 @@ PostgreSQL documentation
       <term><option>--target-pgdata</option></term>
       <listitem>
         <para>
-          This option specifies the target data directory that is synchronized with
-          the source. The target server must cleanly shut down before running
-          <application>pg_rewind</application>
+          This option specifies the target data directory that is synchronized
+          with the source. The target server must shut down cleanly before
+          running <application>pg_rewind</application>
         </para>
       </listitem>
      </varlistentry>
@@ -92,8 +107,9 @@ PostgreSQL documentation
       <term><option>--source-pgdata</option></term>
       <listitem>
         <para>
-          Specifies a source data directory to synchronize the target with. When
-          --source-pgdata is used, the source server master be cleanly shut down.
+          Specifies a source data directory to synchronize the target with.
+          When <option>--source-pgdata</> is used, the source server must be
+          cleanly shut down.
         </para>
       </listitem>
      </varlistentry>
@@ -102,9 +118,9 @@ PostgreSQL documentation
       <term><option>--source-server</option></term>
       <listitem>
         <para>
-          Specifies a libpq connection string to connect to the source PostgreSQL
-          server to synchronize the target with. The server must be up and running,
-          and must not be in recovery mode.
+          Specifies a libpq connection string to connect to the source
+          <productname>PostgreSQL</> server to synchronize the target with.
+          The server must be up and running, and must not be in recovery mode.
         </para>
       </listitem>
      </varlistentry>
@@ -146,7 +162,7 @@ PostgreSQL documentation
       <listitem>
        <para>
         Print verbose debugging output that is mostly useful for developers
-        debugging pg_rewind.
+        debugging <application>pg_rewind</>.
        </para>
       </listitem>
      </varlistentry>
@@ -171,9 +187,9 @@ PostgreSQL documentation
   <title>Environment</title>
 
   <para>
-   When --source-server option is used, <command>pg_rewind</command> also uses the
-   environment variables supported by <application>libpq</> (see
-   <xref linkend="libpq-envars">).
+    When <option>--source-server</> option is used,
+    <application>pg_rewind</application> also uses the environment variables
+    supported by <application>libpq</> (see <xref linkend="libpq-envars">).
   </para>
  </refsect1>
 
@@ -181,8 +197,8 @@ PostgreSQL documentation
   <title>Theory of operation</title>
 
   <para>
-    The basic idea is to copy everything from the new cluster to the old cluster,
-    except for the blocks that we know to be the same.
+    The basic idea is to copy everything from the new cluster to the old
+    cluster, except for the blocks that we know to be the same.
   </para>
 
   <procedure>
@@ -209,10 +225,10 @@ PostgreSQL documentation
      <step>
       <para>
         Apply the WAL from the new cluster, starting from the checkpoint
-        created at failover. (pg_rewind doesn't actually apply the WAL, it
-        just creates a backup label file indicating that when PostgreSQL is
-        started, it will start replay from that checkpoint and apply all the
-        required WAL)
+        created at failover. (Strictly speaking, <application>pg_rewind</>
+        doesn't apply the WAL, it just creates a backup label file indicating
+        that when <productname>PostgreSQL</> is started, it will start replay
+        from that checkpoint and apply all the required WAL.)
       </para>
      </step>
     </procedure>
@@ -222,10 +238,9 @@ PostgreSQL documentation
   <title>Restrictions</title>
 
   <para>
-   <application>pg_rewind</> needs that cluster uses either data checksums that
-   can be enabled at server initialization with initdb or WAL logging of hint
-   bits that can be enabled by settings <varname>wal_log_hints</> to <literal>on</>
-   in <filename>postgresql.conf</>.
+   <application>pg_rewind</> requires that the <varname>wal_log_hints</>
+   option is enabled in <filename>postgresql.conf</>, or that data checksums
+   were enabled when the cluster was initialized with <application>initdb</>.
   </para>
  </refsect1>