From 2f26a02b5cf200f09dcccf8b55a3727fbdfebce2 Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Mon, 20 Apr 2020 12:11:49 +0900
Subject: [PATCH] doc: clarify usage of -F/--force with "standby promote"

Per GitHub #632.
---
 doc/repmgr-standby-promote.xml | 36 ++++++++++++++++++++++++++++++++++
 repmgr-action-standby.c        | 10 +++++++---
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/doc/repmgr-standby-promote.xml b/doc/repmgr-standby-promote.xml
index 3f90b965..04e103f3 100644
--- a/doc/repmgr-standby-promote.xml
+++ b/doc/repmgr-standby-promote.xml
@@ -170,6 +170,42 @@
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>-F</option></term>
+        <term><option>--force</option></term>
+        <listitem>
+          <para>
+            Ignore warnings and continue anyway.
+          </para>
+          <para>
+            This option is relevant in the following situations if <option>--siblings-follow</option> was specified:
+            <itemizedlist spacing="compact" mark="bullet">
+              <listitem>
+                <simpara>
+                  If one or more sibling nodes was not reachable via SSH, the standby will be promoted anyway.
+                </simpara>
+              </listitem>
+              <listitem>
+                <simpara>
+                  If the promotion candidate has insufficient free walsenders to accomodate the standbys which will
+                  be attached to it, the standby will be promoted anyway.
+                </simpara>
+              </listitem>
+              <listitem>
+                <simpara>
+                  If replication slots are in use but the promotion candidate has insufficient free replication slots
+                  to accomodate the standbys which will be attached to it, the standby will be promoted anyway.
+                </simpara>
+              </listitem>
+            </itemizedlist>
+          </para>
+          <para>
+            Note that if the <option>-F</option>/<option>--force</option> option is used when any of the above
+            situations is encountered, the onus is on the user to manually resolve any resulting issues.
+          </para>
+        </listitem>
+      </varlistentry>
+
     </variablelist>
   </refsect1>
 
diff --git a/repmgr-action-standby.c b/repmgr-action-standby.c
index aa99e1cf..d5709e5b 100644
--- a/repmgr-action-standby.c
+++ b/repmgr-action-standby.c
@@ -2390,7 +2390,7 @@ do_standby_promote(void)
 	 */
 	if (check_free_wal_senders(available_wal_senders, &sibling_nodes_stats, &dry_run_success) == false)
 	{
-		if (runtime_options.dry_run == false)
+		if (runtime_options.dry_run == false || runtime_options.force == false)
 		{
 			PQfinish(local_conn);
 			exit(ERR_BAD_CONFIG);
@@ -2404,7 +2404,7 @@ do_standby_promote(void)
 	 */
 	if (check_free_slots(&local_node_record, &sibling_nodes_stats, &dry_run_success) == false)
 	{
-		if (runtime_options.dry_run == false)
+		if (runtime_options.dry_run == false || runtime_options.force == false)
 		{
 			PQfinish(local_conn);
 			exit(ERR_BAD_CONFIG);
@@ -2505,7 +2505,7 @@ _do_standby_promote_internal(PGconn *conn)
 	/*
 	 * Promote standby to primary.
 	 *
-	 * `pg_ctl promote` returns immediately and (prior to 10.0) has no -w
+	 * "pg_ctl promote: returns immediately and (prior to 10.0) has no -w
 	 * option so we can't be sure when or if the promotion completes. For now
 	 * we'll poll the server until the default timeout (60 seconds)
 	 *
@@ -8676,6 +8676,10 @@ do_standby_help(void)
 	puts("");
 	printf(_("  \"standby promote\" promotes a standby node to primary.\n"));
 	puts("");
+	printf(_("  --dry-run                           perform checks etc. but don't actually promote the node\n"));
+	printf(_("  -F, --force                         ignore warnings and continue anyway\n"));
+	printf(_("  --siblings-follow                   have other standbys follow new primary\n"));
+	puts("");
 
 	printf(_("STANDBY FOLLOW\n"));
 	puts("");