From 4695da5ae97bbb58d274887fd68edbe88d03ebcb Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Tue, 15 Feb 2011 21:28:48 -0500
Subject: pg_ctl promote

Fujii Masao, reviewed by Robert Haas, Stephen Frost, and Magnus Hagander.
---
 doc/src/sgml/high-availability.sgml | 24 +++++++++++-------------
 doc/src/sgml/recovery-config.sgml   |  4 ++--
 doc/src/sgml/ref/pg_ctl-ref.sgml    | 13 +++++++++++++
 3 files changed, 26 insertions(+), 15 deletions(-)

(limited to 'doc/src/sgml')

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index a89296905b4..368c68867af 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -615,8 +615,9 @@ protocol to make nodes agree on a serializable transactional order.
    </para>
 
    <para>
-    Standby mode is exited and the server switches to normal operation,
-    when a trigger file is found (<varname>trigger_file</>). Before failover,
+    Standby mode is exited and the server switches to normal operation
+    when <command>pg_ctl promote</> is run or a trigger file is found
+    (<varname>trigger_file</>). Before failover,
     any WAL immediately available in the archive or in <filename>pg_xlog</> will be
     restored, but no attempt is made to connect to the master.
    </para>
@@ -685,11 +686,7 @@ protocol to make nodes agree on a serializable transactional order.
     If you're setting up the standby server for high availability purposes,
     set up WAL archiving, connections and authentication like the primary
     server, because the standby server will work as a primary server after
-    failover. You will also need to set <varname>trigger_file</> to make
-    it possible to fail over.
-    If you're setting up the standby server for reporting
-    purposes, with no plans to fail over to it, <varname>trigger_file</>
-    is not required.
+    failover.
    </para>
 
    <para>
@@ -710,7 +707,6 @@ protocol to make nodes agree on a serializable transactional order.
 standby_mode = 'on'
 primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
 restore_command = 'cp /path/to/archive/%f %p'
-trigger_file = '/path/to/trigger_file'
 archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r'
 </programlisting>
    </para>
@@ -949,13 +945,15 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
    </para>
 
    <para>
-    To trigger failover of a log-shipping standby server, create a trigger
+    To trigger failover of a log-shipping standby server,
+    run <command>pg_ctl promote</> or create a trigger
     file with the filename and path specified by the <varname>trigger_file</>
-    setting in <filename>recovery.conf</>. If <varname>trigger_file</> is
-    not given, there is no way to exit recovery in the standby and promote
-    it to a master. That can be useful for e.g reporting servers that are
+    setting in <filename>recovery.conf</>. If you're planning to use
+    <command>pg_ctl promote</> to fail over, <varname>trigger_file</> is
+    not required. If you're setting up the reporting servers that are
     only used to offload read-only queries from the primary, not for high
-    availability purposes.
+    availability purposes, you don't need to exit recovery in the standby
+    and promote it to a master.
    </para>
   </sect1>
 
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
index 0ccd65e3ee3..602fbe2c76e 100644
--- a/doc/src/sgml/recovery-config.sgml
+++ b/doc/src/sgml/recovery-config.sgml
@@ -343,8 +343,8 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         <listitem>
          <para>
           Specifies a trigger file whose presence ends recovery in the
-          standby. If no trigger file is specified, the standby never exits
-          recovery.
+          standby.  Even if this value is not set, you can still promote
+          the standby using <command>pg_ctl promote</>.
           This setting has no effect if <varname>standby_mode</> is <literal>off</>.
          </para>
         </listitem>
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index 28f415da24b..307f66b8da3 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -75,6 +75,13 @@ PostgreSQL documentation
    <arg>-o <replaceable>options</replaceable></arg>
   </cmdsynopsis>
 
+  <cmdsynopsis>
+   <command>pg_ctl</command>
+   <arg choice="plain">promote</arg>
+   <arg>-s</arg>
+   <arg>-D <replaceable>datadir</replaceable></arg>
+  </cmdsynopsis>
+
   <cmdsynopsis>
    <command>pg_ctl</command>
    <arg choice="plain">reload</arg>
@@ -183,6 +190,12 @@ PostgreSQL documentation
    command-line options.
   </para>
 
+  <para>
+   In <option>promote</option> mode, the standby server that is
+   running in the specified data directory is commanded to exit
+   recovery and begin read-write operations.
+  </para>
+
   <para>
    <option>reload</option> mode simply sends the
    <command>postgres</command> process a <systemitem>SIGHUP</>
-- 
cgit v1.2.3