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 ("follow candidate") to a new upstream node 20 ("follow target"). 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 ("follow candidate") <emphasis>must</emphasis> 31 be running. If the new upstream ("follow target") 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 ("follow candidate"). 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 ("follow target"). 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 ("follow candidate") is capable of following the 173 new upstream node ("follow target"). 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 "node3" (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