From aee13aee5210bb6ab151d20c3006be7dc217c6e8 Mon Sep 17 00:00:00 2001
From: Ian Barwick <barwick@gmail.com>
Date: Thu, 7 Feb 2019 13:28:29 +0900
Subject: [PATCH] doc: note repmgrd behaviour when WAL replay is paused

Related to GitHub #540.
---
 doc/filelist.sgml      |  1 +
 doc/repmgr.sgml        |  1 +
 doc/repmgrd-notes.sgml | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 40 insertions(+)
 create mode 100644 doc/repmgrd-notes.sgml

diff --git a/doc/filelist.sgml b/doc/filelist.sgml
index 6673618f..1e4adf51 100644
--- a/doc/filelist.sgml
+++ b/doc/filelist.sgml
@@ -59,6 +59,7 @@
 <!ENTITY repmgrd-network-split SYSTEM "repmgrd-network-split.sgml">
 <!ENTITY repmgrd-witness-server SYSTEM "repmgrd-witness-server.sgml">
 <!ENTITY repmgrd-pausing SYSTEM "repmgrd-pausing.sgml">
+<!ENTITY repmgrd-notes SYSTEM "repmgrd-notes.sgml">
 <!ENTITY repmgrd-bdr SYSTEM "repmgrd-bdr.sgml">
 
 <!ENTITY repmgr-primary-register SYSTEM "repmgr-primary-register.sgml">
diff --git a/doc/repmgr.sgml b/doc/repmgr.sgml
index 791c9525..fa647fbf 100644
--- a/doc/repmgr.sgml
+++ b/doc/repmgr.sgml
@@ -89,6 +89,7 @@
   &repmgrd-pausing;
   &repmgrd-degraded-monitoring;
   &repmgrd-monitoring;
+  &repmgrd-notes;
   &repmgrd-bdr;
  </part>
 
diff --git a/doc/repmgrd-notes.sgml b/doc/repmgrd-notes.sgml
new file mode 100644
index 00000000..31910758
--- /dev/null
+++ b/doc/repmgrd-notes.sgml
@@ -0,0 +1,38 @@
+<chapter id="repmgrd-notes" xreflabel="repmgrd notes">
+
+  <indexterm>
+    <primary>repmgrd</primary>
+    <secondary>notes</secondary>
+  </indexterm>
+  <title>repmgrd notes</title>
+
+  <sect1 id="repmgrd-wal-replay-pause">
+    <indexterm>
+      <primary>repmgrd</primary>
+      <secondary>paused WAL replay</secondary>
+    </indexterm>
+
+    <title>repmgrd and paused WAL replay</title>
+    <para>
+      If WAL replay has been paused (using <command>pg_wal_replay_pause()</command>,
+      on PostgreSQL 9.6 and earlier <command>pg_xlog_replay_pause()</command>),
+      in a failover situation <application>repmgrd</application> will
+      automatically resume WAL replay.
+    </para>
+    <para>
+      This is because if WAL replay is paused, but WAL is pending replay,
+      PostgreSQL cannot be promoted until WAL replay is resumed.
+    </para>
+    <note>
+      <para>
+        <command><link linkend="repmgr-standby-promote">repmgr standby promote</link></command>
+        will refuse to promote a node in this state, as the PostgreSQL
+        <command>promote</command> command will not be acted on until
+        WAL replay is resumed, leaving the cluster in a potentially
+        unstable state. In this case it is up to the user to
+        decide whether to resume WAL replay.
+      </para>
+    </note>
+  </sect1>
+
+</chapter>