ltcluster 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 ltcluster.conf file for the standby, either
specified explicitly with -f/--config-file or located in a
default location; no additional arguments are required.
If ltclusterd is active, you must execute
ltcluster service pause
(ltcluster 4.2 - 4.4: ltcluster service pause)
to temporarily disable ltclusterd 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 ltcluster 5,
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 ltclusterd, when invoking
ltcluster 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 ltcluster standby promote.
ltcluster 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 ltcluster.conf.
$ ltcluster -f /etc/ltcluster.conf standby promote
NOTICE: promoting standby to primary
DETAIL: promoting server "node2" (ID: 2) using "lt_ctl -l /var/log/lightdb/startup.log -w -D '/var/lib/lightdb/data' promote"
server promoting
NOTICE: STANDBY PROMOTE successful
DETAIL: server "node2" (ID: 2) was successfully promoted to primary
pg_promote() (LightDB 21 and later)
From LightDB 21, ltcluster will attempt to use the built-in pg_promote()
function to promote a standby to primary.
By default, execution of pg_promote() is restricted to superusers.
If the ltcluster user does not have permission to execute
pg_promote(), ltcluster will fall back to using "lt_ctl promote".
Execute ltcluster standby promote with the --dry-run
to check whether the ltcluster user has permission to execute pg_promote().
If the ltcluster user is not a superuser, execution permission for this
function can be granted with e.g.:
GRANT EXECUTE ON FUNCTION pg_catalog.pg_promote TO ltcluster
Note that permissions are only effective for the database they are granted in, so this must be executed in the ltcluster database to be effective.
For more details on pg_promote(), see the
LightDB documentation.
--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
ltclusterd's promote_command.
-F--forceIgnore warnings and continue anyway.
This option is relevant in the following situations if --siblings-follow was specified:
Note that if the -F/--force option is used when any of the above
situations is encountered, the onus is on the user to manually resolve any resulting issues.
The following parameters in ltcluster.conf are relevant to the
promote operation:
promote_check_interval:
interval (in seconds, default: 1 second) to wait between each check
to determine whether the standby has been promoted.
promote_check_timeout:
time (in seconds, default: 60 seconds) to wait to verify that the standby has been promoted
before exiting with ERR_PROMOTION_FAIL.
service_promote_command:
a command which will be executed instead of lt_ctl promote
or (in LightDB 21 and later) pg_promote().
This is intended for systems which provide a package-level promote command, such as Debian's pg_ctlcluster, to promote the LightDB from standby to primary.
Following exit codes can be emitted by ltcluster standby promote:
SUCCESS (0)The standby was successfully promoted to primary.
ERR_DB_CONN (6)ltcluster was unable to connect to the local LightDB node.
LightDB 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.