1<refentry id="repmgr-standby-promote"> 2 <indexterm> 3 <primary>repmgr standby promote</primary> 4 </indexterm> 5 6 <refmeta> 7 <refentrytitle>repmgr standby promote</refentrytitle> 8 </refmeta> 9 10 <refnamediv> 11 <refname>repmgr standby promote</refname> 12 <refpurpose>promote a standby to a primary</refpurpose> 13 </refnamediv> 14 15 <refsect1> 16 <title>Description</title> 17 <para> 18 Promotes a standby to a primary if the current primary has failed. This 19 command requires a valid <filename>repmgr.conf</filename> file for the standby, either 20 specified explicitly with <literal>-f/--config-file</literal> or located in a 21 default location; no additional arguments are required. 22 </para> 23 <important> 24 <para> 25 If &repmgrd; is active, you must execute 26 <command><link linkend="repmgr-service-pause">repmgr service pause</link></command> 27 (&repmgr; 4.2 - 4.4: <command><link linkend="repmgr-service-pause">repmgr service pause</link></command>) 28 to temporarily disable &repmgrd; while making any changes 29 to the replication cluster. 30 </para> 31 </important> 32 33 <para> 34 If the standby promotion succeeds, the server will not need to be 35 restarted. However any other standbys will need to follow the new primary, 36 and will need to be restarted to do this. 37 </para> 38 <para> 39 Beginning with <link linkend="release-4.4">repmgr 4.4</link>, 40 the option <option>--siblings-follow</option> can be used to have 41 all other standbys (and a witness server, if in use) 42 follow the new primary. 43 </para> 44 45 <note> 46 <para> 47 If using &repmgrd;, when invoking 48 <command>repmgr standby promote</command> (either directly via 49 the <option>promote_command</option>, or in a script called 50 via <option>promote_command</option>), <option>--siblings-follow</option> 51 <emphasis>must not</emphasis> be included as a 52 command line option for <command>repmgr standby promote</command>. 53 </para> 54 </note> 55 56 <para> 57 In <link linkend="release-4.3">repmgr 4.3</link> and earlier, 58 <command><link linkend="repmgr-standby-follow">repmgr standby follow</link></command> 59 must be executed on each standby individually. 60 </para> 61 62 <para> 63 &repmgr; will wait for up to <varname>promote_check_timeout</varname> seconds 64 (default: <literal>60</literal>) to verify that the standby has been promoted, and will 65 check the promotion every <varname>promote_check_interval</varname> seconds (default: 1 second). 66 Both values can be defined in <filename>repmgr.conf</filename>. 67 </para> 68 69 <warning> 70 <para> 71 In PostgreSQL 12 and earlier, if WAL replay is paused on the standby, and not all 72 WAL files on the standby have been replayed, &repmgr; will not attempt to promote it. 73 </para> 74 <para> 75 This is because if WAL replay is paused, PostgreSQL itself will not react to a promote command 76 until WAL replay is resumed and all pending WAL has been replayed. This means 77 attempting to promote PostgreSQL in this state will leave PostgreSQL in a condition where the 78 promotion may occur at a unpredictable point in the future. 79 </para> 80 <para> 81 Note that if the standby is in archive recovery, &repmgr; will not be able to determine 82 if more WAL is pending replay, and will abort the promotion attempt if WAL replay is paused. 83 </para> 84 <para> 85 This restriction does <emphasis>not</emphasis> apply to PostgreSQL 13 and later. 86 </para> 87 </warning> 88 89 </refsect1> 90 91 92 93 <refsect1> 94 <title>Example</title> 95 <para> 96 <programlisting> 97 $ repmgr -f /etc/repmgr.conf standby promote 98 NOTICE: promoting standby to primary 99 DETAIL: promoting server "node2" (ID: 2) using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' promote" 100 server promoting 101 NOTICE: STANDBY PROMOTE successful 102 DETAIL: server "node2" (ID: 2) was successfully promoted to primary</programlisting> 103 </para> 104 </refsect1> 105 106 107 <refsect1> 108 <title>User permission requirements</title> 109 <para><emphasis>pg_promote() (PostgreSQL 12 and later)</emphasis></para> 110 <para> 111 From PostgreSQL 12, &repmgr; will attempt to use the built-in <function>pg_promote()</function> 112 function to promote a standby to primary. 113 </para> 114 <para> 115 By default, execution of <function>pg_promote()</function> is restricted to superusers. 116 If the <literal>repmgr</literal> user does not have permission to execute 117 <function>pg_promote()</function>, &repmgr; will fall back to using "<command>pg_ctl promote</command>". 118 </para> 119 <tip> 120 <para> 121 Execute <command>repmgr standby promote</command> with the <option>--dry-run</option> 122 to check whether the &repmgr; user has permission to execute <function>pg_promote()</function>. 123 </para> 124 <para> 125 If the <literal>repmgr</literal> user is not a superuser, execution permission for this 126 function can be granted with e.g.: 127 <programlisting> 128 GRANT EXECUTE ON FUNCTION pg_catalog.pg_promote TO repmgr</programlisting> 129 </para> 130 <para> 131 Note that permissions are only effective for the database they are granted in, so 132 this <emphasis>must</emphasis> be executed in the &repmgr; database to be effective. 133 </para> 134 </tip> 135 <para> 136 For more details on <function>pg_promote()</function>, see the 137 <ulink url="https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-RECOVERY-CONTROL-TABLE">PostgreSQL documentation</ulink>. 138 </para> 139 </refsect1> 140 141 <refsect1> 142 <title>Options</title> 143 <variablelist> 144 <varlistentry> 145 146 <term><option>--dry-run</option></term> 147 <listitem> 148 <para> 149 Check if this node can be promoted, but don't carry out the promotion. 150 </para> 151 </listitem> 152 </varlistentry> 153 154 <varlistentry> 155 <term><option>--siblings-follow</option></term> 156 <listitem> 157 <para> 158 Have all sibling nodes (nodes formerly attached to the same upstream 159 node as the promotion candidate) follow this node after it has been promoted. 160 </para> 161 <para> 162 Note that a witness server, if in use, is also 163 counted as a "sibling node" as it needs to be instructed to 164 synchronise its metadata with the new primary. 165 </para> 166 <important> 167 <para> 168 Do <emphasis>not</emphasis> provide this option when configuring 169 &repmgrd;'s <option>promote_command</option>. 170 </para> 171 </important> 172 </listitem> 173 </varlistentry> 174 175 <varlistentry> 176 <term><option>-F</option></term> 177 <term><option>--force</option></term> 178 <listitem> 179 <para> 180 Ignore warnings and continue anyway. 181 </para> 182 <para> 183 This option is relevant in the following situations if <option>--siblings-follow</option> was specified: 184 <itemizedlist spacing="compact" mark="bullet"> 185 <listitem> 186 <simpara> 187 If one or more sibling nodes was not reachable via SSH, the standby will be promoted anyway. 188 </simpara> 189 </listitem> 190 <listitem> 191 <simpara> 192 If the promotion candidate has insufficient free walsenders to accomodate the standbys which will 193 be attached to it, the standby will be promoted anyway. 194 </simpara> 195 </listitem> 196 <listitem> 197 <simpara> 198 If replication slots are in use but the promotion candidate has insufficient free replication slots 199 to accomodate the standbys which will be attached to it, the standby will be promoted anyway. 200 </simpara> 201 </listitem> 202 </itemizedlist> 203 </para> 204 <para> 205 Note that if the <option>-F</option>/<option>--force</option> option is used when any of the above 206 situations is encountered, the onus is on the user to manually resolve any resulting issues. 207 </para> 208 </listitem> 209 </varlistentry> 210 211 </variablelist> 212 </refsect1> 213 214 <refsect1> 215 <title>Configuration file settings</title> 216 <para> 217 The following parameters in <filename>repmgr.conf</filename> are relevant to the 218 promote operation: 219 </para> 220 221 <para> 222 <itemizedlist spacing="compact" mark="bullet"> 223 224 <listitem> 225 <indexterm> 226 <primary>promote_check_interval</primary> 227 <secondary>with "repmgr standby promote "</secondary> 228 </indexterm> 229 <simpara> 230 <literal>promote_check_interval</literal>: 231 interval (in seconds, default: 1 second) to wait between each check 232 to determine whether the standby has been promoted. 233 </simpara> 234 </listitem> 235 236 <listitem> 237 <indexterm> 238 <primary>promote_check_timeout</primary> 239 <secondary>with "repmgr standby promote "</secondary> 240 </indexterm> 241 <simpara> 242 <literal>promote_check_timeout</literal>: 243 time (in seconds, default: 60 seconds) to wait to verify that the standby has been promoted 244 before exiting with <literal>ERR_PROMOTION_FAIL</literal>. 245 </simpara> 246 </listitem> 247 248 <listitem> 249 <indexterm> 250 <primary>service_promote_command</primary> 251 <secondary>with "repmgr standby promote "</secondary> 252 </indexterm> 253 <simpara> 254 <literal>service_promote_command</literal>: 255 a command which will be executed instead of <command>pg_ctl promote</command> 256 or (in PostgreSQL 12 and later) <function>pg_promote()</function>. 257 </simpara> 258 <simpara> 259 This is intended for systems which provide a package-level promote command, 260 such as Debian's <application>pg_ctlcluster</application>, to promote the 261 PostgreSQL from standby to primary. 262 </simpara> 263 </listitem> 264 265 </itemizedlist> 266 </para> 267 268 </refsect1> 269 270 <refsect1> 271 <title>Exit codes</title> 272 <para> 273 Following exit codes can be emitted by <command>repmgr standby promote</command>: 274 </para> 275 <variablelist> 276 <varlistentry> 277 <term><option>SUCCESS (0)</option></term> 278 <listitem> 279 <para> 280 The standby was successfully promoted to primary. 281 </para> 282 </listitem> 283 </varlistentry> 284 285 <varlistentry> 286 <term><option>ERR_DB_CONN (6)</option></term> 287 <listitem> 288 <para> 289 &repmgr; was unable to connect to the local PostgreSQL node. 290 </para> 291 <para> 292 PostgreSQL must be running before the node can be promoted. 293 </para> 294 </listitem> 295 </varlistentry> 296 297 <varlistentry> 298 <term><option>ERR_PROMOTION_FAIL (8)</option></term> 299 <listitem> 300 <para> 301 The node could not be promoted to primary for one of the following 302 reasons: 303 <itemizedlist spacing="compact" mark="bullet"> 304 305 <listitem> 306 <simpara> 307 there is an existing primary node in the replication cluster 308 </simpara> 309 </listitem> 310 311 <listitem> 312 <simpara> 313 the node is not a standby 314 </simpara> 315 </listitem> 316 317 <listitem> 318 <simpara> 319 WAL replay is paused on the node 320 </simpara> 321 </listitem> 322 323 <listitem> 324 <simpara> 325 execution of the PostgreSQL promote command failed 326 </simpara> 327 </listitem> 328 329 </itemizedlist> 330 </para> 331 </listitem> 332 </varlistentry> 333 334 </variablelist> 335 </refsect1> 336 337 338 <refsect1 id="repmgr-standby-promote-events"> 339 <title>Event notifications</title> 340 <para> 341 A <literal>standby_promote</literal> <link linkend="event-notifications">event notification</link> will be generated. 342 </para> 343 </refsect1> 344 345</refentry> 346