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 $ pg_autoctl show state
56 Name | Node | Host:Port | LSN | Connection | Current State | Assigned State
57 ------+-------+----------------+-----------+--------------+---------------------+--------------------
58 node1 | 1 | localhost:5501 | 0/4000F88 | read-only | secondary | secondary
59 node2 | 2 | localhost:5502 | 0/4000F88 | read-write | primary | primary
60 node3 | 3 | localhost:5503 | 0/4000F88 | read-only | secondary | secondary
61 $ pg_autoctl perform promotion --name node1
64 13:08:13 15297 INFO Listening monitor notifications about state changes in formation "default" and group 0
65 13:08:13 15297 INFO Following table displays times when notifications are received
66 Time | Name | Node | Host:Port | Current State | Assigned State
67 ---------+-------+-------+----------------+---------------------+--------------------
68 13:08:13 | node1 | 0/1 | localhost:5501 | secondary | secondary
69 13:08:13 | node2 | 0/2 | localhost:5502 | primary | draining
70 13:08:13 | node2 | 0/2 | localhost:5502 | draining | draining
71 13:08:13 | node1 | 0/1 | localhost:5501 | secondary | report_lsn
72 13:08:13 | node3 | 0/3 | localhost:5503 | secondary | report_lsn
73 13:08:19 | node3 | 0/3 | localhost:5503 | report_lsn | report_lsn
74 13:08:19 | node1 | 0/1 | localhost:5501 | report_lsn | report_lsn
75 13:08:19 | node1 | 0/1 | localhost:5501 | report_lsn | prepare_promotion
76 13:08:19 | node1 | 0/1 | localhost:5501 | prepare_promotion | prepare_promotion
77 13:08:19 | node1 | 0/1 | localhost:5501 | prepare_promotion | stop_replication
78 13:08:19 | node2 | 0/2 | localhost:5502 | draining | demote_timeout
79 13:08:19 | node3 | 0/3 | localhost:5503 | report_lsn | join_secondary
80 13:08:19 | node2 | 0/2 | localhost:5502 | demote_timeout | demote_timeout
81 13:08:19 | node3 | 0/3 | localhost:5503 | join_secondary | join_secondary
82 13:08:20 | node1 | 0/1 | localhost:5501 | stop_replication | stop_replication
83 13:08:20 | node1 | 0/1 | localhost:5501 | stop_replication | wait_primary
84 13:08:20 | node2 | 0/2 | localhost:5502 | demote_timeout | demoted
85 13:08:20 | node1 | 0/1 | localhost:5501 | wait_primary | wait_primary
86 13:08:20 | node3 | 0/3 | localhost:5503 | join_secondary | secondary
87 13:08:20 | node2 | 0/2 | localhost:5502 | demoted | demoted
88 13:08:20 | node2 | 0/2 | localhost:5502 | demoted | catchingup
89 13:08:21 | node3 | 0/3 | localhost:5503 | secondary | secondary
90 13:08:21 | node1 | 0/1 | localhost:5501 | wait_primary | primary
91 13:08:21 | node2 | 0/2 | localhost:5502 | catchingup | catchingup
92 13:08:21 | node1 | 0/1 | localhost:5501 | primary | primary
93 $ pg_autoctl show state
95 Name | Node | Host:Port | LSN | Connection | Current State | Assigned State
96 ------+-------+----------------+-----------+--------------+---------------------+--------------------
97 node1 | 1 | localhost:5501 | 0/40012F0 | read-write | primary | primary
98 node2 | 2 | localhost:5502 | 0/40012F0 | read-only | secondary | secondary
99 node3 | 3 | localhost:5503 | 0/40012F0 | read-only | secondary | secondary
100
102 Microsoft
103
105 Copyright (c) Microsoft Corporation. All rights reserved.
1061.6 Jan 21, 2022 PG_AUTOCTL PERFORM PROMOTION(1)