repmgr standby promote — promote a standby to a primary
Promotes a standby to a primary if the current primary has failed. This
command requires a valid repmgr.conf file for the standby, either
specified explicitly with -f/--config-file or located in a
default location; no additional arguments are required.
If repmgrd is active, you must execute
repmgr service pause
(repmgr 4.2 - 4.4: repmgr service pause)
to temporarily disable repmgrd while making any changes
to the replication cluster.
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.
Beginning with repmgr 4.4,
the option --siblings-follow can be used to have
all other standbys (and a witness server, if in use)
follow the new primary.
If using repmgrd, when invoking
repmgr standby promote (either directly via
the promote_command, or in a script called
via promote_command), --siblings-follow
must not be included as a
command line option for repmgr standby promote.
In repmgr 4.3 and earlier,
repmgr standby follow
must be executed on each standby individually.
repmgr will wait for up to promote_check_timeout seconds
(default: 60) to verify that the standby has been promoted, and will
check the promotion every promote_check_interval seconds (default: 1 second).
Both values can be defined in repmgr.conf.
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.
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.
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.
$ 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
pg_promote() (PostgreSQL 12)
From PostgreSQL 12, repmgr uses the pg_promote() function to promote a standby
to primary.
By default, execution of pg_promote() is restricted to superusers.
If the repmgr use is not a superuser, execution permission for this
function must be granted with e.g.:
GRANT EXECUTE ON FUNCTION pg_catalog.pg_promote TO repmgr
Note that permissions are only effective for the database they are granted in, so this must be executed in the repmgr database to be effective.
A future repmgr release will relax this restriction by falling back to
pg_ctl promote, as used for pre-PostgreSQL 12 versions.
--dry-runCheck if this node can be promoted, but don't carry out the promotion.
--siblings-followHave all sibling nodes (nodes formerly attached to the same upstream node as the promotion candidate) follow this node after it has been promoted.
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.
Do not provide this option when configuring
repmgrd's promote_command.
The following parameters in repmgr.conf are relevant to the
promote operation:
Following exit codes can be emitted by repmgr standby promote:
SUCCESS (0)The standby was successfully promoted to primary.
ERR_DB_CONN (6)repmgr was unable to connect to the local PostgreSQL node.
PostgreSQL must be running before the node can be promoted.
ERR_PROMOTION_FAIL (8)The node could not be promoted to primary for one of the following reasons:
A standby_promote event notification will be generated.