1PG_AUTOCTL PERFORM PROMOTION(1)pg_auto_failoverPG_AUTOCTL PERFORM PROMOTION(1)
2
6 pg_autoctl perform promotion - pg_autoctl perform promotion
7 pg_autoctl perform promotion - Perform a failover that promotes a tar‐
9 get node
10
12 This command starts a Postgres failover orchestration from the
13 pg_auto_promotion monitor and targets given node:
14 usage: pg_autoctl perform promotion [ --pgdata --formation --group ]
16 --pgdata path to data directory
18 --formation formation to target, defaults to 'default'
19 --name node name to target, defaults to current node
20 --wait how many seconds to wait, default to 60
21
23 The pg_auto_promotion monitor can be used to orchestrate a manual pro‐
24 motion, 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 promotion command waits until the promotion is
29 known complete on the monitor, or until the hard-coded 60s timeout has
30 passed.
31 The promotion orchestration is done in the background by the monitor,
33 so even if the pg_autoctl perform promotion stops on the timeout, the
34 promotion 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 --name Name of the node that should be elected as the new primary node.
47 --wait How many seconds to wait for notifications about the promotion.
49 The command stops when the promotion is finished (a node is pri‐
50 mary), or when the timeout has elapsed, whichever comes first.
51 The value 0 (zero) disables the timeout and allows the command
52 to wait forever.
53
55 PGDATA
56 Postgres directory location. Can be used instead of the --pgdata op‐
57 tion.
58 PG_AUTOCTL_MONITOR
60 Postgres URI to connect to the monitor node, can be used instead of
61 the --monitor option.
62 PG_CONFIG
64 Can be set to the absolute path to the pg_config Postgres tool. This
65 is mostly used in the context of building extensions, though it can
66 be a useful way to select a Postgres version when several are in‐
67 stalled on the same system.
68 PATH
70 Used the usual way mostly. Some entries that are searched in the
71 PATH by the pg_autoctl command are expected to be found only once,
72 to avoid mistakes with Postgres major versions.
73 PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ...
75 See the Postgres docs about Environment Variables for details.
76 TMPDIR
78 The pgcopydb command creates all its work files and directories in
79 ${TMPDIR}/pgcopydb, and defaults to /tmp/pgcopydb.
80 XDG_CONFIG_HOME
82 The pg_autoctl command stores its configuration files in the stan‐
83 dard place XDG_CONFIG_HOME. See the XDG Base Directory Specifica‐
84 tion.
85 XDG_DATA_HOME
87 The pg_autoctl command stores its internal states files in the stan‐
88 dard place XDG_DATA_HOME, which defaults to ~/.local/share. See the
89 XDG Base Directory Specification.
90
92 $ pg_autoctl show state
93 Name | Node | Host:Port | LSN | Connection | Current State | Assigned State
94 ------+-------+----------------+-----------+--------------+---------------------+--------------------
95 node1 | 1 | localhost:5501 | 0/4000F88 | read-only | secondary | secondary
96 node2 | 2 | localhost:5502 | 0/4000F88 | read-write | primary | primary
97 node3 | 3 | localhost:5503 | 0/4000F88 | read-only | secondary | secondary
98 $ pg_autoctl perform promotion --name node1
101 13:08:13 15297 INFO Listening monitor notifications about state changes in formation "default" and group 0
102 13:08:13 15297 INFO Following table displays times when notifications are received
103 Time | Name | Node | Host:Port | Current State | Assigned State
104 ---------+-------+-------+----------------+---------------------+--------------------
105 13:08:13 | node1 | 0/1 | localhost:5501 | secondary | secondary
106 13:08:13 | node2 | 0/2 | localhost:5502 | primary | draining
107 13:08:13 | node2 | 0/2 | localhost:5502 | draining | draining
108 13:08:13 | node1 | 0/1 | localhost:5501 | secondary | report_lsn
109 13:08:13 | node3 | 0/3 | localhost:5503 | secondary | report_lsn
110 13:08:19 | node3 | 0/3 | localhost:5503 | report_lsn | report_lsn
111 13:08:19 | node1 | 0/1 | localhost:5501 | report_lsn | report_lsn
112 13:08:19 | node1 | 0/1 | localhost:5501 | report_lsn | prepare_promotion
113 13:08:19 | node1 | 0/1 | localhost:5501 | prepare_promotion | prepare_promotion
114 13:08:19 | node1 | 0/1 | localhost:5501 | prepare_promotion | stop_replication
115 13:08:19 | node2 | 0/2 | localhost:5502 | draining | demote_timeout
116 13:08:19 | node3 | 0/3 | localhost:5503 | report_lsn | join_secondary
117 13:08:19 | node2 | 0/2 | localhost:5502 | demote_timeout | demote_timeout
118 13:08:19 | node3 | 0/3 | localhost:5503 | join_secondary | join_secondary
119 13:08:20 | node1 | 0/1 | localhost:5501 | stop_replication | stop_replication
120 13:08:20 | node1 | 0/1 | localhost:5501 | stop_replication | wait_primary
121 13:08:20 | node2 | 0/2 | localhost:5502 | demote_timeout | demoted
122 13:08:20 | node1 | 0/1 | localhost:5501 | wait_primary | wait_primary
123 13:08:20 | node3 | 0/3 | localhost:5503 | join_secondary | secondary
124 13:08:20 | node2 | 0/2 | localhost:5502 | demoted | demoted
125 13:08:20 | node2 | 0/2 | localhost:5502 | demoted | catchingup
126 13:08:21 | node3 | 0/3 | localhost:5503 | secondary | secondary
127 13:08:21 | node1 | 0/1 | localhost:5501 | wait_primary | primary
128 13:08:21 | node2 | 0/2 | localhost:5502 | catchingup | catchingup
129 13:08:21 | node1 | 0/1 | localhost:5501 | primary | primary
130 $ pg_autoctl show state
132 Name | Node | Host:Port | LSN | Connection | Current State | Assigned State
133 ------+-------+----------------+-----------+--------------+---------------------+--------------------
134 node1 | 1 | localhost:5501 | 0/40012F0 | read-write | primary | primary
135 node2 | 2 | localhost:5502 | 0/40012F0 | read-only | secondary | secondary
136 node3 | 3 | localhost:5503 | 0/40012F0 | read-only | secondary | secondary
137
139 Microsoft
140
142 Copyright (c) Microsoft Corporation. All rights reserved.
1432.0 Sep 13, 2023 PG_AUTOCTL PERFORM PROMOTION(1)