mirror of
https://github.com/EnterpriseDB/repmgr.git
synced 2026-03-22 22:56:29 +00:00
931da14df1
"repmgr daemon" can be interpreted to mean the commands affect the local daemon process only. Rename the commands which affect the entire cluster to "repmgr service ...". The "repmgr daemon ..." form of the affected commands is retained for backwards compatibility.
256 lines
8.2 KiB
XML
256 lines
8.2 KiB
XML
<refentry id="repmgr-standby-promote">
|
|
<indexterm>
|
|
<primary>repmgr standby promote</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle>repmgr standby promote</refentrytitle>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>repmgr standby promote</refname>
|
|
<refpurpose>promote a standby to a primary</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
Promotes a standby to a primary if the current primary has failed. This
|
|
command requires a valid <filename>repmgr.conf</filename> file for the standby, either
|
|
specified explicitly with <literal>-f/--config-file</literal> or located in a
|
|
default location; no additional arguments are required.
|
|
</para>
|
|
<important>
|
|
<para>
|
|
If &repmgrd; is active, you must execute
|
|
<command><link linkend="repmgr-service-pause">repmgr service pause</link></command>
|
|
(&repmgr; 4.2 - 4.4: <command><link linkend="repmgr-service-pause">repmgr service pause</link></command>)
|
|
to temporarily disable &repmgrd; while making any changes
|
|
to the replication cluster.
|
|
</para>
|
|
</important>
|
|
|
|
<para>
|
|
If the standby promotion succeeds, the server will not need to be
|
|
restarted. However any other standbys will need to follow the new primary,
|
|
and will need to be restarted to do this.
|
|
</para>
|
|
<para>
|
|
Beginning with <link linkend="release-4.4">repmgr 4.4</link>,
|
|
the option <option>--siblings-follow</option> can be used to have
|
|
all other standbys (and a witness server, if in use)
|
|
follow the new primary.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
If using &repmgrd;, when invoking
|
|
<command>repmgr standby promote</command> (either directly via
|
|
the <option>promote_command</option>, or in a script called
|
|
via <option>promote_command</option>), <option>--siblings-follow</option>
|
|
<emphasis>must not</emphasis> be included as a
|
|
command line option for <command>repmgr standby promote</command>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
In <link linkend="release-4.3">repmgr 4.3</link> and earlier,
|
|
<command><link linkend="repmgr-standby-follow">repmgr standby follow</link></command>
|
|
must be executed on each standby individually.
|
|
</para>
|
|
|
|
<para>
|
|
&repmgr; will wait for up to <varname>promote_check_timeout</varname> seconds
|
|
(default: <literal>60</literal>) to verify that the standby has been promoted, and will
|
|
check the promotion every <varname>promote_check_interval</varname> seconds (default: 1 second).
|
|
Both values can be defined in <filename>repmgr.conf</filename>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
If WAL replay is paused on the standby, and not all WAL files on the standby have been
|
|
replayed, &repmgr; will not attempt to promote it.
|
|
</para>
|
|
<para>
|
|
This is because if WAL replay is paused, PostgreSQL itself will not react to a promote command
|
|
until WAL replay is resumed and all pending WAL has been replayed. This means
|
|
attempting to promote PostgreSQL in this state will leave PostgreSQL in a condition where the
|
|
promotion may occur at a unpredictable point in the future.
|
|
</para>
|
|
<para>
|
|
Note that if the standby is in archive recovery, &repmgr; will not be able to determine
|
|
if more WAL is pending replay, and will abort the promotion attempt if WAL replay is paused.
|
|
</para>
|
|
</note>
|
|
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
<para>
|
|
<programlisting>
|
|
$ repmgr -f /etc/repmgr.conf standby promote
|
|
NOTICE: promoting standby to primary
|
|
DETAIL: promoting server "node2" (ID: 2) using "pg_ctl -l /var/log/postgres/startup.log -w -D '/var/lib/postgres/data' promote"
|
|
server promoting
|
|
DEBUG: setting node 2 as primary and marking existing primary as failed
|
|
NOTICE: STANDBY PROMOTE successful
|
|
DETAIL: server "node2" (ID: 2) was successfully promoted to primary</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
|
|
<term><option>--dry-run</option></term>
|
|
<listitem>
|
|
<para>
|
|
Check if this node can be promoted, but don't carry out the promotion.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--siblings-follow</option></term>
|
|
<listitem>
|
|
<para>
|
|
Have all sibling nodes (nodes formerly attached to the same upstream
|
|
node as the promotion candidate) follow this node after it has been promoted.
|
|
</para>
|
|
<para>
|
|
Note that a witness server, if in use, is also
|
|
counted as a "sibling node" as it needs to be instructed to
|
|
synchronise its metadata with the new primary.
|
|
</para>
|
|
<important>
|
|
<para>
|
|
Do <emphasis>not</emphasis> provide this option when configuring
|
|
&repmgrd;'s <option>promote_command</option>.
|
|
</para>
|
|
</important>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Configuration file settings</title>
|
|
<para>
|
|
The following parameters in <filename>repmgr.conf</filename> are relevant to the
|
|
promote operation:
|
|
</para>
|
|
|
|
<para>
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
|
|
<listitem>
|
|
<indexterm>
|
|
<primary>promote_check_interval</primary>
|
|
<secondary>with "repmgr standby promote "</secondary>
|
|
</indexterm>
|
|
<simpara>
|
|
<literal>promote_check_interval</literal>:
|
|
interval (in seconds, default: 1 second) to wait between each check
|
|
to determine whether the standby has been promoted.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<indexterm>
|
|
<primary>promote_check_timeout</primary>
|
|
<secondary>with "repmgr standby promote "</secondary>
|
|
</indexterm>
|
|
<simpara>
|
|
<literal>promote_check_timeout</literal>:
|
|
time (in seconds, default: 60 seconds) to wait to verify that the standby has been promoted
|
|
before exiting with <literal>ERR_PROMOTION_FAIL</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Exit codes</title>
|
|
<para>
|
|
Following exit codes can be emitted by <command>repmgr standby promote</command>:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>SUCCESS (0)</option></term>
|
|
<listitem>
|
|
<para>
|
|
The standby was successfully promoted to primary.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ERR_DB_CONN (6)</option></term>
|
|
<listitem>
|
|
<para>
|
|
&repmgr; was unable to connect to the local PostgreSQL node.
|
|
</para>
|
|
<para>
|
|
PostgreSQL must be running before the node can be promoted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>ERR_PROMOTION_FAIL (8)</option></term>
|
|
<listitem>
|
|
<para>
|
|
The node could not be promoted to primary for one of the following
|
|
reasons:
|
|
<itemizedlist spacing="compact" mark="bullet">
|
|
|
|
<listitem>
|
|
<simpara>
|
|
there is an existing primary node in the replication cluster
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
the node is not a standby
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
WAL replay is paused on the node
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
execution of the PostgreSQL promote command failed
|
|
</simpara>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1 id="repmgr-standby-promote-events">
|
|
<title>Event notifications</title>
|
|
<para>
|
|
A <literal>standby_promote</literal> <link linkend="event-notifications">event notification</link> will be generated.
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|