1PG_AUTOCTL PERFORM FAILOVER(1) pg_auto_failover PG_AUTOCTL PERFORM FAILOVER(1)
2
6 pg_autoctl perform failover - pg_autoctl perform failover
7 pg_autoctl perform failover - Perform a failover for given formation
9 and group
10
12 This command starts a Postgres failover orchestration from the
13 pg_auto_failover monitor:
14 usage: pg_autoctl perform failover [ --pgdata --formation --group ]
16 --pgdata path to data directory
18 --formation formation to target, defaults to 'default'
19 --group group to target, defaults to 0
20 --wait how many seconds to wait, default to 60
21
23 The pg_auto_failover monitor can be used to orchestrate a manual
24 failover, sometimes also known as a switchover. When doing so,
25 split-brain are prevented thanks to intermediary states being used in
26 the Finite State Machine.
27 The pg_autoctl perform failover command waits until the failover is
29 known complete on the monitor, or until the hard-coded 60s timeout has
30 passed.
31 The failover orchestration is done in the background by the monitor, so
33 even if the pg_autoctl perform failover stops on the timeout, the
34 failover orchestration continues at the monitor.
35
37 --pgdata
38 Location of the Postgres node being managed locally. Defaults to
39 the environment variable PGDATA. Use --monitor to connect to a
40 monitor from anywhere, rather than the monitor URI used by a lo‐
41 cal Postgres node managed with pg_autoctl.
42 --formation
44 Formation to target for the operation. Defaults to default.
45 --group
47 Postgres group to target for the operation. Defaults to 0, only
48 Citus formations may have more than one group.
49 --wait How many seconds to wait for notifications about the promotion.
51 The command stops when the promotion is finished (a node is pri‐
52 mary), or when the timeout has elapsed, whichever comes first.
53 The value 0 (zero) disables the timeout and allows the command
54 to wait forever.
55
57 PGDATA
58 Postgres directory location. Can be used instead of the --pgdata op‐
59 tion.
60 PG_AUTOCTL_MONITOR
62 Postgres URI to connect to the monitor node, can be used instead of
63 the --monitor option.
64 PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ...
66 See the Postgres docs about Environment Variables for details.
67 TMPDIR
69 The pgcopydb command creates all its work files and directories in
70 ${TMPDIR}/pgcopydb, and defaults to /tmp/pgcopydb.
71 XDG_CONFIG_HOME
73 The pg_autoctl command stores its configuration files in the stan‐
74 dard place XDG_CONFIG_HOME. See the XDG Base Directory Specifica‐
75 tion.
76 XDG_DATA_HOME
78 The pg_autoctl command stores its internal states files in the stan‐
79 dard place XDG_DATA_HOME, which defaults to ~/.local/share. See the
80 XDG Base Directory Specification.
81
83 $ pg_autoctl perform failover
84 12:57:30 3635 INFO Listening monitor notifications about state changes in formation "default" and group 0
85 12:57:30 3635 INFO Following table displays times when notifications are received
86 Time | Name | Node | Host:Port | Current State | Assigned State
87 ---------+-------+-------+----------------+---------------------+--------------------
88 12:57:30 | node1 | 1 | localhost:5501 | primary | draining
89 12:57:30 | node1 | 1 | localhost:5501 | draining | draining
90 12:57:30 | node2 | 2 | localhost:5502 | secondary | report_lsn
91 12:57:30 | node3 | 3 | localhost:5503 | secondary | report_lsn
92 12:57:36 | node3 | 3 | localhost:5503 | report_lsn | report_lsn
93 12:57:36 | node2 | 2 | localhost:5502 | report_lsn | report_lsn
94 12:57:36 | node2 | 2 | localhost:5502 | report_lsn | prepare_promotion
95 12:57:36 | node2 | 2 | localhost:5502 | prepare_promotion | prepare_promotion
96 12:57:36 | node2 | 2 | localhost:5502 | prepare_promotion | stop_replication
97 12:57:36 | node1 | 1 | localhost:5501 | draining | demote_timeout
98 12:57:36 | node3 | 3 | localhost:5503 | report_lsn | join_secondary
99 12:57:36 | node1 | 1 | localhost:5501 | demote_timeout | demote_timeout
100 12:57:36 | node3 | 3 | localhost:5503 | join_secondary | join_secondary
101 12:57:37 | node2 | 2 | localhost:5502 | stop_replication | stop_replication
102 12:57:37 | node2 | 2 | localhost:5502 | stop_replication | wait_primary
103 12:57:37 | node1 | 1 | localhost:5501 | demote_timeout | demoted
104 12:57:37 | node1 | 1 | localhost:5501 | demoted | demoted
105 12:57:37 | node2 | 2 | localhost:5502 | wait_primary | wait_primary
106 12:57:37 | node3 | 3 | localhost:5503 | join_secondary | secondary
107 12:57:37 | node1 | 1 | localhost:5501 | demoted | catchingup
108 12:57:38 | node3 | 3 | localhost:5503 | secondary | secondary
109 12:57:38 | node2 | 2 | localhost:5502 | wait_primary | primary
110 12:57:38 | node1 | 1 | localhost:5501 | catchingup | catchingup
111 12:57:38 | node2 | 2 | localhost:5502 | primary | primary
112 $ pg_autoctl show state
114 Name | Node | Host:Port | LSN | Connection | Current State | Assigned State
115 ------+-------+----------------+-----------+--------------+---------------------+--------------------
116 node1 | 1 | localhost:5501 | 0/4000F50 | read-only | secondary | secondary
117 node2 | 2 | localhost:5502 | 0/4000F50 | read-write | primary | primary
118 node3 | 3 | localhost:5503 | 0/4000F50 | read-only | secondary | secondary
119
121 Microsoft
122
124 Copyright (c) Microsoft Corporation. All rights reserved.
1252.0 Sep 13, 2023 PG_AUTOCTL PERFORM FAILOVER(1)