From 9697e2ccfccc4de604899af309e7d50c41b3bd2c Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Fri, 22 Sep 2017 17:31:09 +0900
Subject: [PATCH] Add standby promotion documentation

---
 doc/filelist.sgml           |  2 ++
 doc/follow-new-primary.sgml | 42 +++++++++++++++++++++++++++++++++++++
 doc/promoting-standby.sgml  |  5 +++--
 3 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 doc/follow-new-primary.sgml

diff --git a/doc/filelist.sgml b/doc/filelist.sgml
index 5d16624a..5ab55cd3 100644
--- a/doc/filelist.sgml
+++ b/doc/filelist.sgml
@@ -41,7 +41,9 @@
 <!ENTITY configuration-file-settings      SYSTEM "configuration-file-settings.sgml">
 <!ENTITY cloning-standbys  SYSTEM "cloning-standbys.sgml">
 <!ENTITY promoting-standby  SYSTEM "promoting-standby.sgml">
+<!ENTITY follow-new-primary  SYSTEM "follow-new-primary.sgml">
 <!ENTITY command-reference SYSTEM "command-reference.sgml">
 <!ENTITY appendix-signatures      SYSTEM "appendix-signatures.sgml">
 
 <!ENTITY bookindex  SYSTEM "bookindex.sgml">
+
diff --git a/doc/follow-new-primary.sgml b/doc/follow-new-primary.sgml
new file mode 100644
index 00000000..d1e8f65f
--- /dev/null
+++ b/doc/follow-new-primary.sgml
@@ -0,0 +1,42 @@
+<chapter id="follow-new-primary" xreflabel="Following a new primary">
+ <title>Following a new primary</title>
+ <para>
+   Following the failure or removal of the replication cluster's existing primary
+   server, <xref linkend="repmgr-standby-follow"> can be used to make 'orphaned' standbys
+   follow the new primary and catch up to its current state.
+ </para>
+ <para>
+  To demonstrate this, assuming a replication cluster in the same state as the
+  end of the preceding section (<xref linkend="promoting-standby">),
+  execute this:
+  <programlisting>
+    $ repmgr -f /etc/repmgr.conf repmgr standby follow
+    INFO: changing node 3's primary to node 2
+    NOTICE: restarting server using "pg_ctl -l /var/log/postgresql/startup.log -w -D '/var/lib/postgresql/data' restart"
+    waiting for server to shut down......... done
+    server stopped
+    waiting for server to start.... done
+    server started
+    NOTICE: STANDBY FOLLOW successful
+    DETAIL: node 3 is now attached to node 2
+  </programlisting>
+ </para>
+ <para>
+   The standby is now replicating from the new primary and `repmgr cluster show`
+   output reflects this:
+   <programlisting>
+    $ repmgr -f /etc/repmgr.conf cluster show
+     ID | Name  | Role    | Status    | Upstream | Location | Connection string
+    ----+-------+---------+-----------+----------+----------+--------------------------------------
+     1  | node1 | primary | - failed  |          | default  | host=node1 dbname=repmgr user=repmgr
+     2  | node2 | primary | * running |          | default  | host=node2 dbname=repmgr user=repmgr
+     3  | node3 | standby |   running | node2    | default  | host=node3 dbname=repmgr user=repmgr</programlisting>
+ </para>
+ <para>
+  Note that with cascading replication, <command>repmgr standby follow</command> can also be
+  used to detach a standby from its current upstream server and follow the
+  primary. However it's currently not possible to have it follow another standby;
+  we hope to improve this in a future release.
+ </para>
+
+</chapter>
diff --git a/doc/promoting-standby.sgml b/doc/promoting-standby.sgml
index de515951..95cf1158 100644
--- a/doc/promoting-standby.sgml
+++ b/doc/promoting-standby.sgml
@@ -1,4 +1,4 @@
-<chapter id="promoting-standby" xreflabel="promoting a standby">
+<chapter id="promoting-standby" xreflabel="Promoting a standby">
  <title>Promoting a standby server with repmgr</title>
  <para>
    If a primary server fails or needs to be removed from the replication cluster,
@@ -68,7 +68,8 @@
  </para>
  <para>
   However the sole remaining standby (<literal>node3</literal>) is still trying to replicate from the failed
-  primary; <xref linkend="repmgr-standby-follow"> must now be executed to rectify this situation.
+  primary; <xref linkend="repmgr-standby-follow"> must now be executed to rectify this situation
+  (see <xref linkend="follow-new-primary"> for example).
  </para>
 </chapter>