PG_AUTOCTL PERFORM FAILOVER(1)

📦
version 2.2 · 6 versions
, in debian trixie, ubuntu questing

💖 PG_AUTOCTL PERFORM FAILOVER 💖

okay bestie, welcome to the pg_autoctl perform failover manual page, straight out of the pg_auto_failover collection (section 1, yes she's a section 1 girlie) 💅

✨ NAME ✨

pg_autoctl perform failover — that's the command name, and also literally what she does: she performs a failover 🎀

and more precisely: perform a failover for a given formation and group. no cap.

🌸 SYNOPSIS 🌸

so this command kicks off a Postgres failover orchestration from the pg_auto_failover monitor 👑

usage: pg_autoctl perform failover  [ --pgdata --formation --group ]

--pgdata      path to data directory
--formation   formation to target, defaults to 'default'
--group       group to target, defaults to 0
--wait        how many seconds to wait, default to 60

🦋 DESCRIPTION 🦋

the pg_auto_failover monitor can be used to orchestrate a manual failover — which, fun fact, is also sometimes called a switchover 🌈 and when she does it, split-brain is prevented because the Finite State Machine uses intermediary states. that's the whole point, the FSM is the bodyguard 🫶

the pg_autoctl perform failover command waits until the failover is known complete on the monitor, or until the hard-coded 60s timeout has passed ⏳ whichever comes first, no exceptions.

and here's the plot twist, bestie: the failover orchestration is done in the background by the monitor. so even if pg_autoctl perform failover stops because of the timeout, the failover orchestration continues at the monitor. she does not abandon the mission 💅

🎀 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.
  • --group — Postgres group to target for the operation. defaults to 0. only Citus formations may have more than one group 👑
  • --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 lets the command wait forever 😭 periodt.

🌈 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.
  • 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 ⭐

watch her cook 🍓

$ pg_autoctl perform failover
12:57:30 3635 INFO  Listening monitor notifications about state changes in formation "default" and group 0
12:57:30 3635 INFO  Following table displays times when notifications are received
    Time |  Name |  Node |      Host:Port |       Current State |      Assigned State
---------+-------+-------+----------------+---------------------+--------------------
12:57:30 | node1 |     1 | localhost:5501 |             primary |            draining
12:57:30 | node1 |     1 | localhost:5501 |            draining |            draining
12:57:30 | node2 |     2 | localhost:5502 |           secondary |          report_lsn
12:57:30 | node3 |     3 | localhost:5503 |           secondary |          report_lsn
12:57:36 | node3 |     3 | localhost:5503 |          report_lsn |          report_lsn
12:57:36 | node2 |     2 | localhost:5502 |          report_lsn |          report_lsn
12:57:36 | node2 |     2 | localhost:5502 |          report_lsn |   prepare_promotion
12:57:36 | node2 |     2 | localhost:5502 |   prepare_promotion |   prepare_promotion
12:57:36 | node2 |     2 | localhost:5502 |   prepare_promotion |    stop_replication
12:57:36 | node1 |     1 | localhost:5501 |            draining |      demote_timeout
12:57:36 | node3 |     3 | localhost:5503 |          report_lsn |      join_secondary
12:57:36 | node1 |     1 | localhost:5501 |      demote_timeout |      demote_timeout
12:57:36 | node3 |     3 | localhost:5503 |      join_secondary |      join_secondary
12:57:37 | node2 |     2 | localhost:5502 |    stop_replication |    stop_replication
12:57:37 | node2 |     2 | localhost:5502 |    stop_replication |        wait_primary
12:57:37 | node1 |     1 | localhost:5501 |      demote_timeout |             demoted
12:57:37 | node1 |     1 | localhost:5501 |             demoted |             demoted
12:57:37 | node2 |     2 | localhost:5502 |        wait_primary |        wait_primary
12:57:37 | node3 |     3 | localhost:5503 |      join_secondary |           secondary
12:57:37 | node1 |     1 | localhost:5501 |             demoted |          catchingup
12:57:38 | node3 |     3 | localhost:5503 |           secondary |           secondary
12:57:38 | node2 |     2 | localhost:5502 |        wait_primary |             primary
12:57:38 | node1 |     1 | localhost:5501 |          catchingup |          catchingup
12:57:38 | node2 |     2 | localhost:5502 |             primary |             primary

$ pg_autoctl show state
 Name |  Node |      Host:Port |       LSN |   Connection |       Current State |      Assigned State
------+-------+----------------+-----------+--------------+---------------------+--------------------
node1 |     1 | localhost:5501 | 0/4000F50 |    read-only |           secondary |           secondary
node2 |     2 | localhost:5502 | 0/4000F50 |   read-write |             primary |             primary
node3 |     3 | localhost:5503 | 0/4000F50 |    read-only |           secondary |           secondary

look at node2 going from report_lsn to prepare_promotion to stop_replication to wait_primary to primary 😭 she ATE. the FSM journey is giving main character energy fr fr 👑

👑 AUTHOR 👑

Microsoft ✨

Copyright (c) Microsoft Corporation. All rights reserved.

and that's the whole page, bestie 🫶 this was pg_autoctl perform failover from pg_auto_failover version 2.2, dated Apr 07, 2025 — slay, mwah 💅🎀🌸

📦 where this page comes from