1<refentry id="repmgr-standby-switchover"> 2 <indexterm> 3 <primary>repmgr standby switchover</primary> 4 </indexterm> 5 6 <refmeta> 7 <refentrytitle>repmgr standby switchover</refentrytitle> 8 </refmeta> 9 10 <refnamediv> 11 <refname>repmgr standby switchover</refname> 12 <refpurpose>promote a standby to primary and demote the existing primary to a standby</refpurpose> 13 </refnamediv> 14 15 16 <refsect1> 17 <title>Description</title> 18 19 <para> 20 Promotes a standby to primary and demotes the existing primary to a standby. 21 This command must be run on the standby to be promoted, and requires a 22 passwordless SSH connection to the current primary. 23 </para> 24 <para> 25 If other nodes are connected to the demotion candidate, &repmgr; can instruct 26 these to follow the new primary if the option <literal>--siblings-follow</literal> 27 is specified. This requires a passwordless SSH connection between the promotion 28 candidate (new primary) and the nodes attached to the demotion candidate 29 (existing primary). Note that a witness server, if in use, is also 30 counted as a "sibling node" as it needs to be instructed to 31 synchronise its metadata with the new primary. 32 </para> 33 <note> 34 <para> 35 Performing a switchover is a non-trivial operation. In particular it 36 relies on the current primary being able to shut down cleanly and quickly. 37 &repmgr; will attempt to check for potential issues but cannot guarantee 38 a successful switchover. 39 </para> 40 <para> 41 &repmgr; will refuse to perform the switchover if an exclusive backup is running on 42 the current primary, or if WAL replay is paused on the standby. 43 </para> 44 </note> 45 <para> 46 For more details on performing a switchover, including preparation and configuration, 47 see section <xref linkend="performing-switchover"/>. 48 </para> 49 50 <note> 51 <para> 52 From <link linkend="release-4.2">repmgr 4.2</link>, &repmgr; will instruct any running 53 &repmgrd; instances to pause operations while the switchover 54 is being carried out, to prevent &repmgrd; from 55 unintentionally promoting a node. For more details, see <xref linkend="repmgrd-pausing"/>. 56 </para> 57 <para> 58 Users of &repmgr; versions prior to 4.2 should ensure that &repmgrd; 59 is not running on any nodes while a switchover is being executed. 60 </para> 61 </note> 62 63 </refsect1> 64 65 <refsect1> 66 <title>User permission requirements</title> 67 <para><emphasis>CHECKPOINT</emphasis></para> 68 <para> 69 &repmgr; executes <command>CHECKPOINT</command> on the demotion candidate as part of the shutdown 70 process to ensure it shuts down as smoothly as possible. 71 </para> 72 <para> 73 Note that <command>CHECKPOINT</command> requires database superuser permissions to execute. 74 If the <literal>repmgr</literal> user is not a superuser, the name of a superuser should be 75 provided with the <option>-S</option>/<option>--superuser</option>. 76 </para> 77 <para> 78 If &repmgr; is unable to execute the <command>CHECKPOINT</command> command, the switchover 79 can still be carried out, albeit at a greater risk that the demotion candidate may not 80 be able to shut down as smoothly as might otherwise have been the case. 81 </para> 82 <para><emphasis>pg_promote() (PostgreSQL 12 and later)</emphasis></para> 83 <para> 84 From PostgreSQL 12, &repmgr; defaults to using the built-in <command>pg_promote()</command> function to 85 promote a standby to primary. 86 </para> 87 <para> 88 Note that execution of <function>pg_promote()</function> is restricted to superusers or to 89 any user who has been granted execution permission for this function. If the &repmgr; user 90 is not permitted to execute <function>pg_promote()</function>, &repmgr; will fall back to using 91 "<command>pg_ctl promote</command>". For more details see 92 <link linkend="repmgr-standby-promote">repmgr standby promote</link>. 93 </para> 94 </refsect1> 95 96 <refsect1> 97 98 <title>Options</title> 99 <variablelist> 100 101 <varlistentry> 102 <term><option>--always-promote</option></term> 103 <listitem> 104 <para> 105 Promote standby to primary, even if it is behind or has diverged 106 from the original primary. The original primary will be shut down in any case, 107 and will need to be manually reintegrated into the replication cluster. 108 </para> 109 </listitem> 110 </varlistentry> 111 112 <varlistentry> 113 <term><option>--dry-run</option></term> 114 <listitem> 115 <para> 116 Check prerequisites but don't actually execute a switchover. 117 </para> 118 <important> 119 <para> 120 Success of <option>--dry-run</option> does not imply the switchover will 121 complete successfully, only that 122 the prerequisites for performing the operation are met. 123 </para> 124 </important> 125 </listitem> 126 </varlistentry> 127 128 <varlistentry> 129 <term><option>-F</option></term> 130 <term><option>--force</option></term> 131 <listitem> 132 <para> 133 Ignore warnings and continue anyway. 134 </para> 135 <para> 136 Specifically, if a problem is encountered when shutting down the current primary, 137 using <option>-F/--force</option> will cause &repmgr; to continue by promoting 138 the standby to be the new primary, and if <option>--siblings-follow</option> is 139 specified, attach any other standbys to the new primary. 140 </para> 141 </listitem> 142 </varlistentry> 143 144 <varlistentry> 145 <term><option>--force-rewind[=/path/to/pg_rewind]</option></term> 146 <listitem> 147 <para> 148 Use <application>pg_rewind</application> to reintegrate the old primary if necessary 149 (and the prerequisites for using <application>pg_rewind</application> are met). 150 If using PostgreSQL 9.4, and the <application>pg_rewind</application> 151 binary is not installed in the PostgreSQL <filename>bin</filename> directory, 152 provide its full path. For more details see also <xref linkend="switchover-pg-rewind"/>. 153 </para> 154 </listitem> 155 </varlistentry> 156 157 <varlistentry> 158 <term><option>-R</option></term> 159 <term><option>--remote-user</option></term> 160 <listitem> 161 <para> 162 System username for remote SSH operations (defaults to local system user). 163 </para> 164 </listitem> 165 </varlistentry> 166 167 <varlistentry> 168 <term><option>--repmgrd-no-pause</option></term> 169 <listitem> 170 <para> 171 Don't pause &repmgrd; while executing a switchover. 172 </para> 173 <para> 174 This option should not be used unless you take steps by other means 175 to ensure &repmgrd; is paused or not 176 running on all nodes. 177 </para> 178 <para> 179 This option cannot be used together with <option>--repmgrd-force-unpause</option>. 180 </para> 181 182 </listitem> 183 </varlistentry> 184 185 <varlistentry> 186 <term><option>--repmgrd-force-unpause</option></term> 187 <listitem> 188 <para> 189 Always unpause all &repmgrd; instances after executing a switchover. This will ensure that 190 any &repmgrd; instances which were paused before the switchover will be 191 unpaused. 192 </para> 193 <para> 194 This option cannot be used together with <option>--repmgrd-no-pause</option>. 195 </para> 196 </listitem> 197 </varlistentry> 198 199 200 <varlistentry> 201 202 <term><option>--siblings-follow</option></term> 203 <listitem> 204 <para> 205 Have nodes attached to the old primary follow the new primary. 206 </para> 207 <para> 208 This will also ensure that a witness node, if in use, is updated 209 with the new primary's data. 210 </para> 211 <note> 212 <para> 213 In a future &repmgr; release, <option>--siblings-follow</option> will be applied 214 by default. 215 </para> 216 </note> 217 </listitem> 218 </varlistentry> 219 220 <varlistentry> 221 <term><option>-S</option>/<option>--superuser</option></term> 222 <listitem> 223 <para> 224 Use the named superuser instead of the normal &repmgr; user to perform 225 actions requiring superuser permissions. 226 </para> 227 </listitem> 228 </varlistentry> 229 230 </variablelist> 231 232 </refsect1> 233 234 <refsect1> 235 <title>Configuration file settings</title> 236 237 <para> 238 The following parameters in <filename>repmgr.conf</filename> are relevant to the 239 switchover operation: 240 </para> 241 242 <variablelist> 243 244 <varlistentry> 245 <term><option>replication_lag_critical</option></term> 246 <listitem> 247 248 <indexterm> 249 <primary>replication_lag_critical</primary> 250 <secondary>with "repmgr standby switchover"</secondary> 251 </indexterm> 252 253 <para> 254 If replication lag (in seconds) on the standby exceeds this value, the 255 switchover will be aborted (unless the <literal>-F/--force</literal> option 256 is provided) 257 </para> 258 </listitem> 259 </varlistentry> 260 261 <varlistentry> 262 263 <term><option>shutdown_check_timeout</option></term> 264 <listitem> 265 <indexterm> 266 <primary>shutdown_check_timeout</primary> 267 <secondary>with "repmgr standby switchover"</secondary> 268 </indexterm> 269 270 <para> 271 The maximum number of seconds to wait for the 272 demotion candidate (current primary) to shut down, before aborting the switchover. 273 </para> 274 <para> 275 Note that this parameter is set on the node where <command>repmgr standby switchover</command> 276 is executed (promotion candidate); setting it on the demotion candidate (former primary) will 277 have no effect. 278 </para> 279 <note> 280 <para> 281 In versions prior to <link linkend="release-4.2">&repmgr; 4.2</link>, <command>repmgr standby switchover</command> would 282 use the values defined in <literal>reconnect_attempts</literal> and <literal>reconnect_interval</literal> 283 to determine the timeout for demotion candidate shutdown. 284 </para> 285 </note> 286 </listitem> 287 </varlistentry> 288 289 290 <varlistentry> 291 <term><option>wal_receive_check_timeout</option></term> 292 <listitem> 293 <indexterm> 294 <primary>wal_receive_check_timeout</primary> 295 <secondary>with "repmgr standby switchover"</secondary> 296 </indexterm> 297 298 <para> 299 After the primary has shut down, the maximum number of seconds to wait for the 300 walreceiver on the standby to flush WAL to disk before comparing WAL receive location 301 with the primary's shut down location. 302 </para> 303 </listitem> 304 </varlistentry> 305 306 307 <varlistentry> 308 309 <term><option>standby_reconnect_timeout</option></term> 310 <listitem> 311 <indexterm> 312 <primary>standby_reconnect_timeout</primary> 313 <secondary>with "repmgr standby switchover"</secondary> 314 </indexterm> 315 316 <para> 317 The maximum number of seconds to attempt to wait for the demotion candidate (former primary) 318 to reconnect to the promoted primary (default: 60 seconds) 319 </para> 320 <para> 321 Note that this parameter is set on the node where <command>repmgr standby switchover</command> 322 is executed (promotion candidate); setting it on the demotion candidate (former primary) will 323 have no effect. 324 </para> 325 </listitem> 326 </varlistentry> 327 328 <varlistentry> 329 330 <term><option>node_rejoin_timeout</option></term> 331 <listitem> 332 333 <indexterm> 334 <primary>node_rejoin_timeout</primary> 335 <secondary>with "repmgr standby switchover"</secondary> 336 </indexterm> 337 338 <para> 339 maximum number of seconds to attempt to wait for the demotion candidate (former primary) 340 to reconnect to the promoted primary (default: 60 seconds) 341 </para> 342 <para> 343 Note that this parameter is set on the the demotion candidate (former primary); 344 setting it on the node where <command>repmgr standby switchover</command> is 345 executed will have no effect. 346 </para> 347 <para> 348 However, this value <emphasis>must</emphasis> be less than <option>standby_reconnect_timeout</option> on the 349 promotion candidate (the node where <command>repmgr standby switchover</command> is executed). 350 </para> 351 </listitem> 352 </varlistentry> 353 354 </variablelist> 355 356 </refsect1> 357 358 359 <refsect1> 360 <title>Execution</title> 361 362 <para> 363 Execute with the <literal>--dry-run</literal> option to test the switchover as far as 364 possible without actually changing the status of either node. 365 </para> 366 367 <para> 368 External database connections, e.g. from an application, should not be permitted while 369 the switchover is taking place. In particular, active transactions on the primary 370 can potentially disrupt the shutdown process. 371 </para> 372 </refsect1> 373 374 <refsect1 id="repmgr-standby-switchover-events"> 375 <title>Event notifications</title> 376 <para> 377 <literal>standby_switchover</literal> and <literal>standby_promote</literal> 378 <link linkend="event-notifications">event notifications</link> will be generated for the new primary, 379 and a <literal>node_rejoin</literal> event notification for the former primary (new standby). 380 </para> 381 <para> 382 If using an event notification script, <literal>standby_switchover</literal> 383 will populate the placeholder parameter <literal>%p</literal> with the node ID of 384 the former primary. 385 </para> 386 </refsect1> 387 388 <refsect1> 389 <title>Exit codes</title> 390 <para> 391 One of the following exit codes will be emitted by <command>repmgr standby switchover</command>: 392 </para> 393 <variablelist> 394 395 <varlistentry> 396 <term><option>SUCCESS (0)</option></term> 397 <listitem> 398 <para> 399 The switchover completed successfully; or if <option>--dry-run</option> was provided, 400 no issues were detected which would prevent the switchover operation. 401 </para> 402 </listitem> 403 </varlistentry> 404 405 <varlistentry> 406 <term><option>ERR_SWITCHOVER_FAIL (18)</option></term> 407 <listitem> 408 <para> 409 The switchover could not be executed. 410 </para> 411 </listitem> 412 </varlistentry> 413 414 <varlistentry> 415 <term><option>ERR_SWITCHOVER_INCOMPLETE (22)</option></term> 416 <listitem> 417 <para> 418 The switchover was executed but a problem was encountered. 419 Typically this means the former primary could not be reattached 420 as a standby. Check preceding log messages for more information. 421 </para> 422 </listitem> 423 </varlistentry> 424 425 </variablelist> 426 </refsect1> 427 428 <refsect1> 429 <title>See also</title> 430 <para> 431 <xref linkend="repmgr-standby-follow"/>, <xref linkend="repmgr-node-rejoin"/> 432 </para> 433 <para> 434 For more details on performing a switchover operation, see the section <xref linkend="performing-switchover"/>. 435 </para> 436 </refsect1> 437 438</refentry> 439