1<refentry id="repmgr-standby-follow">
2  <indexterm>
3    <primary>repmgr standby follow</primary>
4  </indexterm>
5
6  <refmeta>
7    <refentrytitle>repmgr standby follow</refentrytitle>
8  </refmeta>
9
10  <refnamediv>
11    <refname>repmgr standby follow</refname>
12    <refpurpose>attach a running standby to a new upstream node</refpurpose>
13  </refnamediv>
14
15  <refsect1>
16    <title>Description</title>
17
18    <para>
19      Attaches the standby (&quot;follow candidate&quot;) to a new upstream node
20      (&quot;follow target&quot;). Typically this will be the primary, but this
21      command can also be used to attach the standby to another standby.
22    </para>
23
24    <para>
25      This command requires a valid <filename>repmgr.conf</filename> file for the standby,
26      either specified explicitly with <literal>-f/--config-file</literal> or located in a
27      default location; no additional arguments are required.
28    </para>
29
30    <para>The standby node (&quot;follow candidate&quot;) <emphasis>must</emphasis>
31      be running. If the new upstream (&quot;follow target&quot;) is not the primary,
32      the cluster primary <emphasis>must</emphasis> be running and accessible from the
33      standby node.
34    </para>
35
36    <tip>
37      <para>
38        To re-add an inactive node to the replication cluster, use
39        <xref linkend="repmgr-node-rejoin"/>.
40      </para>
41    </tip>
42
43    <para>
44      By default &repmgr; will attempt to attach the standby to the current primary.
45      If <option>--upstream-node-id</option> is provided, &repmgr; will attempt
46      to attach the standby to the specified node, which can be another standby.
47    </para>
48
49    <para>
50      In PostgreSQL 12 and earlier, this command will force a restart of PostgreSQL on the standby node.
51    </para>
52
53    <para>
54      In PostgreSQL 13 and later, by default this command will signal PostgreSQL to reload its
55      configuration, which will cause PostgreSQL to follow the new upstream without
56      a restart. If this behaviour is not desired for whatever reason, the configuration
57      file parameter <varname>standby_follow_restart</varname> can be set <literal>true</literal>
58      to always force a restart.
59    </para>
60
61    <para>
62      <command>repmgr standby follow</command> will wait up to
63      <varname>standby_follow_timeout</varname> seconds (default: <literal>30</literal>)
64      to verify the standby has actually connected to the new upstream node.
65    </para>
66
67    <note>
68      <para>
69        If <option>recovery_min_apply_delay</option> is set for the standby, it
70        will not attach to the new upstream node until it has replayed available
71        WAL.
72      </para>
73      <para>
74        Conversely, if the standby is attached to an upstream standby
75        which has <option>recovery_min_apply_delay</option> set, the upstream
76        standby's replay state may actually be behind that of its new downstream node.
77      </para>
78    </note>
79
80  </refsect1>
81
82  <refsect1>
83    <title>Example</title>
84    <para>
85      <programlisting>
86      $ repmgr -f /etc/repmgr.conf standby follow
87      INFO: setting node 3's primary to node 2
88      NOTICE: restarting server using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' restart"
89      waiting for server to shut down........ done
90      server stopped
91      waiting for server to start.... done
92      server started
93      NOTICE: STANDBY FOLLOW successful
94      DETAIL: node 3 is now attached to node 2</programlisting>
95    </para>
96  </refsect1>
97
98  <refsect1>
99    <title>Options</title>
100    <variablelist>
101
102      <varlistentry>
103        <term><option>--dry-run</option></term>
104        <listitem>
105          <para>
106            Check prerequisites but don't actually follow a new upstream node.
107          </para>
108          <para>
109            This will also verify whether the standby is capable of following the new upstream node.
110          </para>
111          <important>
112            <para>
113              If a standby was turned into a primary by removing <filename>recovery.conf</filename>
114              (<application>PostgreSQL 12</application> and later: <filename>standby.signal</filename>),
115              &repmgr; will <emphasis>not</emphasis> be able to determine whether that primary's timeline
116              has diverged from the timeline of the standby (&quot;follow candidate&quot;).
117            </para>
118            <para>
119              We recommend always to use <link linkend="repmgr-standby-promote"><command>repmgr standby promote</command></link>
120              to promote a standby to primary, as this will ensure that the new primary
121              will perform a timeline switch (making it practical to check for timeline divergence)
122              and also that &repmgr; metadata is updated correctly.
123            </para>
124          </important>
125        </listitem>
126      </varlistentry>
127
128      <varlistentry>
129        <term><option>--upstream-node-id</option></term>
130        <listitem>
131          <para>
132            Node ID of the new upstream node (&quot;follow target&quot;).
133          </para>
134          <para>
135            If not provided, &repmgr; will attempt to follow the current primary node.
136          </para>
137          <para>
138            Note that when using &repmgrd;, <option>--upstream-node-id</option>
139            should always be configured;
140            see <link linkend="repmgrd-automatic-failover-configuration">Automatic failover configuration</link>
141            for details.
142          </para>
143        </listitem>
144      </varlistentry>
145
146      <varlistentry>
147        <term><option>-w</option></term>
148        <term><option>--wait</option></term>
149        <listitem>
150          <para>
151            Wait for a primary to appear. &repmgr; will wait for up to
152            <varname>primary_follow_timeout</varname> seconds
153            (default: 60 seconds) to verify that the standby is following the new primary.
154            This value can be defined in <filename>repmgr.conf</filename>.
155          </para>
156        </listitem>
157      </varlistentry>
158
159    </variablelist>
160  </refsect1>
161
162  <refsect1>
163    <title>Execution</title>
164
165    <para>
166      Execute with the <literal>--dry-run</literal> option to test the follow operation as
167      far as possible, without actually changing the status of the node.
168    </para>
169
170    <para>
171      Note that &repmgr; will first attempt to determine whether the standby
172      (&quot;follow candidate&quot;) is capable of following the
173      new upstream node (&quot;follow target&quot;).
174    </para>
175    <para>
176      If, for example, the new upstream node has diverged from this node's timeline,
177      for example if the new upstream node was promoted to primary while this node
178      was still attached to the original primary, it will <emphasis>not</emphasis>
179      be possible to follow the new upstream node, and &repmgr; will emit an error
180      message like this:
181      <programlisting>
182ERROR: this node cannot attach to follow target node &quot;node3&quot; (ID 3)
183DETAIL: follow target server's timeline 2 forked off current database system timeline 1 before current recovery point 0/6108880</programlisting>
184    </para>
185    <para>
186      In this case, it may be possible to have this node follow the new upstream
187      using <command><link linkend="repmgr-node-rejoin">repmgr node rejoin</link></command>
188      with the <option>--force-rewind</option> to execute <command>pg_rewind</command>.
189      This does mean that transactions which exist on this node, but not the new upstream,
190      will be lost.
191    </para>
192
193  </refsect1>
194
195  <refsect1>
196    <title>Exit codes</title>
197    <para>
198      One of the following exit codes will be emitted by <command>repmgr standby follow</command>:
199    </para>
200    <variablelist>
201
202      <varlistentry>
203        <term><option>SUCCESS (0)</option></term>
204        <listitem>
205          <para>
206            The follow operation succeeded; or if <option>--dry-run</option> was provided,
207            no issues were detected which would prevent the follow operation.
208          </para>
209        </listitem>
210      </varlistentry>
211
212      <varlistentry>
213        <term><option>ERR_BAD_CONFIG (1)</option></term>
214        <listitem>
215          <para>
216            A configuration issue was detected which prevented &repmgr; from
217            continuing with the follow operation.
218          </para>
219        </listitem>
220      </varlistentry>
221
222      <varlistentry>
223        <term><option>ERR_NO_RESTART (4)</option></term>
224        <listitem>
225          <para>
226            The node could not be restarted.
227          </para>
228        </listitem>
229      </varlistentry>
230
231      <varlistentry>
232        <term><option>ERR_DB_CONN (6)</option></term>
233        <listitem>
234          <para>
235            &repmgr; was unable to establish a database connection to one of the nodes.
236          </para>
237        </listitem>
238      </varlistentry>
239
240      <varlistentry>
241        <term><option>ERR_FOLLOW_FAIL (23)</option></term>
242        <listitem>
243          <para>
244            &repmgr; was unable to complete the follow command.
245          </para>
246        </listitem>
247      </varlistentry>
248
249    </variablelist>
250
251  </refsect1>
252
253  <refsect1 id="repmgr-standby-follow-events">
254    <title>Event notifications</title>
255    <para>
256      A <literal>standby_follow</literal> <link linkend="event-notifications">event notification</link> will be generated.
257    </para>
258    <para>
259      If provided, &repmgr; will substitute the placeholders <literal>%p</literal> with the node ID of the node
260      being followed, <literal>%c</literal> with its <literal>conninfo</literal> string, and
261      <literal>%a</literal> with its node name.
262    </para>
263  </refsect1>
264
265  <refsect1>
266    <title>See also</title>
267    <para>
268     <xref linkend="repmgr-node-rejoin"/>
269    </para>
270  </refsect1>
271</refentry>
272