table of contents
| PG_AUTOCTL PERFORM PROMOTION(1) | pg_auto_failover | PG_AUTOCTL PERFORM PROMOTION(1) |
NAME¶
pg_autoctl perform promotion - pg_autoctl perform promotion
pg_autoctl perform promotion - Perform a failover that promotes a target node
SYNOPSIS¶
This command starts a Postgres failover orchestration from the pg_auto_promotion monitor and targets given node:
usage: pg_autoctl perform promotion [ --pgdata --formation --group ] --pgdata path to data directory --formation formation to target, defaults to 'default' --name node name to target, defaults to current node --wait how many seconds to wait, default to 60
DESCRIPTION¶
The pg_auto_promotion monitor can be used to orchestrate a manual promotion, sometimes also known as a switchover. When doing so, split-brain are prevented thanks to intermediary states being used in the Finite State Machine.
The pg_autoctl perform promotion command waits until the promotion is known complete on the monitor, or until the hard-coded 60s timeout has passed.
The promotion orchestration is done in the background by the monitor, so even if the pg_autoctl perform promotion stops on the timeout, the promotion orchestration continues at the monitor.
OPTIONS¶
- --pgdata
- Location of the Postgres node being managed locally. Defaults to the environment variable PGDATA. Use --monitor to connect to a monitor from anywhere, rather than the monitor URI used by a local Postgres node managed with pg_autoctl.
- --formation
- Formation to target for the operation. Defaults to default.
- --name
- Name of the node that should be elected as the new primary node.
- --wait
- How many seconds to wait for notifications about the promotion. The command stops when the promotion is finished (a node is primary), or when the timeout has elapsed, whichever comes first. The value 0 (zero) disables the timeout and allows the command to wait forever.
ENVIRONMENT¶
PGDATA
Postgres directory location. Can be used instead of the
--pgdata option.
PG_AUTOCTL_MONITOR
Postgres URI to connect to the monitor node, can be used
instead of the --monitor option.
PG_CONFIG
Can be set to the absolute path to the pg_config
Postgres tool. This is mostly used in the context of building extensions,
though it can be a useful way to select a Postgres version when several are
installed on the same system.
PATH
Used the usual way mostly. Some entries that are searched
in the PATH by the pg_autoctl command are expected to be found only
once, to avoid mistakes with Postgres major versions.
PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ...
See the Postgres docs about Environment Variables
for details.
TMPDIR
The pgcopydb command creates all its work files and
directories in ${TMPDIR}/pgcopydb, and defaults to
/tmp/pgcopydb.
XDG_CONFIG_HOME
The pg_autoctl command stores its configuration files in
the standard place XDG_CONFIG_HOME. See the XDG Base Directory
Specification.
XDG_DATA_HOME
The pg_autoctl command stores its internal states files
in the standard place XDG_DATA_HOME, which defaults to ~/.local/share.
See the XDG Base Directory Specification.
EXAMPLES¶
$ pg_autoctl show state
Name | Node | Host:Port | LSN | Connection | Current State | Assigned State ------+-------+----------------+-----------+--------------+---------------------+-------------------- node1 | 1 | localhost:5501 | 0/4000F88 | read-only | secondary | secondary node2 | 2 | localhost:5502 | 0/4000F88 | read-write | primary | primary node3 | 3 | localhost:5503 | 0/4000F88 | read-only | secondary | secondary $ pg_autoctl perform promotion --name node1 13:08:13 15297 INFO Listening monitor notifications about state changes in formation "default" and group 0 13:08:13 15297 INFO Following table displays times when notifications are received
Time | Name | Node | Host:Port | Current State | Assigned State ---------+-------+-------+----------------+---------------------+-------------------- 13:08:13 | node1 | 0/1 | localhost:5501 | secondary | secondary 13:08:13 | node2 | 0/2 | localhost:5502 | primary | draining 13:08:13 | node2 | 0/2 | localhost:5502 | draining | draining 13:08:13 | node1 | 0/1 | localhost:5501 | secondary | report_lsn 13:08:13 | node3 | 0/3 | localhost:5503 | secondary | report_lsn 13:08:19 | node3 | 0/3 | localhost:5503 | report_lsn | report_lsn 13:08:19 | node1 | 0/1 | localhost:5501 | report_lsn | report_lsn 13:08:19 | node1 | 0/1 | localhost:5501 | report_lsn | prepare_promotion 13:08:19 | node1 | 0/1 | localhost:5501 | prepare_promotion | prepare_promotion 13:08:19 | node1 | 0/1 | localhost:5501 | prepare_promotion | stop_replication 13:08:19 | node2 | 0/2 | localhost:5502 | draining | demote_timeout 13:08:19 | node3 | 0/3 | localhost:5503 | report_lsn | join_secondary 13:08:19 | node2 | 0/2 | localhost:5502 | demote_timeout | demote_timeout 13:08:19 | node3 | 0/3 | localhost:5503 | join_secondary | join_secondary 13:08:20 | node1 | 0/1 | localhost:5501 | stop_replication | stop_replication 13:08:20 | node1 | 0/1 | localhost:5501 | stop_replication | wait_primary 13:08:20 | node2 | 0/2 | localhost:5502 | demote_timeout | demoted 13:08:20 | node1 | 0/1 | localhost:5501 | wait_primary | wait_primary 13:08:20 | node3 | 0/3 | localhost:5503 | join_secondary | secondary 13:08:20 | node2 | 0/2 | localhost:5502 | demoted | demoted 13:08:20 | node2 | 0/2 | localhost:5502 | demoted | catchingup 13:08:21 | node3 | 0/3 | localhost:5503 | secondary | secondary 13:08:21 | node1 | 0/1 | localhost:5501 | wait_primary | primary 13:08:21 | node2 | 0/2 | localhost:5502 | catchingup | catchingup 13:08:21 | node1 | 0/1 | localhost:5501 | primary | primary $ pg_autoctl show state
Name | Node | Host:Port | LSN | Connection | Current State | Assigned State ------+-------+----------------+-----------+--------------+---------------------+-------------------- node1 | 1 | localhost:5501 | 0/40012F0 | read-write | primary | primary node2 | 2 | localhost:5502 | 0/40012F0 | read-only | secondary | secondary node3 | 3 | localhost:5503 | 0/40012F0 | read-only | secondary | secondary
AUTHOR¶
Microsoft
COPYRIGHT¶
Copyright (c) Microsoft Corporation. All rights reserved.
| November 25, 2023 | 2.1 |