From 8c6e3adbf792c2bba448e88cbf2c8e03fb802e73 Mon Sep 17 00:00:00 2001
From: Simon Riggs <simon@2ndQuadrant.com>
Date: Tue, 8 Feb 2011 18:30:22 +0000
Subject: Basic Recovery Control functions for use in Hot Standby. Pause,
 Resume, Status check functions only. Also, new recovery.conf parameter to
 pause_at_recovery_target, default on.

Simon Riggs, reviewed by Fujii Masao
---
 doc/src/sgml/func.sgml            | 58 +++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/recovery-config.sgml | 25 +++++++++++++++++
 2 files changed, 83 insertions(+)

(limited to 'doc/src')

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2bbada0d068..e26e7614c94 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -14173,6 +14173,64 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
     </tgroup>
    </table>
 
+   <para>
+    The functions shown in <xref
+    linkend="functions-recovery-control-table"> control the progress of recovery.
+    These functions may be executed only during recovery.
+   </para>
+
+   <table id="functions-recovery-control-table">
+    <title>Recovery Control Functions</title>
+    <tgroup cols="3">
+     <thead>
+      <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+      </row>
+     </thead>
+
+     <tbody>
+      <row>
+       <entry>
+        <literal><function>pg_is_xlog_replay_paused()</function></literal>
+        </entry>
+       <entry><type>bool</type></entry>
+       <entry>True if recovery is paused.
+       </entry>
+      </row>
+      <row>
+       <entry>
+        <literal><function>pg_xlog_replay_pause()</function></literal>
+        </entry>
+       <entry><type>void</type></entry>
+       <entry>Pauses recovery immediately.
+       </entry>
+      </row>
+      <row>
+       <entry>
+        <literal><function>pg_xlog_replay_resume()</function></literal>
+        </entry>
+       <entry><type>void</type></entry>
+       <entry>Restarts recovery if it was paused.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
+   <para>
+    While recovery is paused no further database changes are applied.
+    If in hot standby, all new queries will see the same consistent snapshot
+    of the database, and no further query conflicts will be generated until
+    recovery is resumed.
+   </para>
+
+   <para>
+    If streaming replication is disabled, the paused state may continue
+    indefinitely without problem. While streaming replication is in
+    progress WAL records will continue to be received, which will
+    eventually fill available disk space, depending upon the duration of
+    the pause, the rate of WAL generation and available disk space.
+   </para>
+
    <para>
     The functions shown in <xref linkend="functions-admin-dbsize"> calculate
     the disk space usage of database objects.
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
index 454ec84f1ab..190e589032a 100644
--- a/doc/src/sgml/recovery-config.sgml
+++ b/doc/src/sgml/recovery-config.sgml
@@ -227,6 +227,31 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
       </listitem>
      </varlistentry>
 
+     <varlistentry id="pause-at-recovery-target"
+                   xreflabel="pause_at_recovery_target">
+      <term><varname>pause_at_recovery_target</varname>
+        (<type>boolean</type>)
+      </term>
+      <indexterm>
+        <primary><varname>pause_at_recovery_target</> recovery parameter</primary>
+      </indexterm>
+      <listitem>
+       <para>
+        Specifies whether recovery should pause when the recovery target
+        is reached. The default is true, if a recovery target is set.
+        This is intended to allow queries to be executed against the
+        database to check if this recovery target is the most desirable
+        point for recovery. The paused state can be resumed by using
+        <function>pg_xlog_replay_resume()</> (See
+        <xref linkend="functions-recovery-control-table">), which then
+        causes recovery to end. If this recovery target is not the
+        desired stopping point, then shutdown the server, change the
+        recovery target settings to a later target and restart to
+        continue recovery.
+       </para>
+      </listitem>
+     </varlistentry>
+
      </variablelist>
    </sect1>
 
-- 
cgit v1.2.3