PG_AUTOCTL PERFORM SWITCHOVER(1)

💖 PG_AUTOCTL PERFORM SWITCHOVER(1) 💖

okay bestie, pull up a chair because we're reading the pg_autoctl perform switchover manual page from pg_auto_failover, section 1 of the manual. yes it's a whole manual page for one command. yes it's iconic. let's get into it 🎀

---

✨ NAME ✨

pg_autoctl perform switchover — pg_autoctl perform switchover

pg_autoctl perform switchover — Perform a switchover for given formation and group

like. the name says it. it performs the switchover. no notes 💅

---

🌸 SYNOPSIS 🌸

so this command kicks off a Postgres switchover orchestration from the pg_auto_switchover monitor:

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

--pgdata      path to data directory
--formation   formation to target, defaults to 'default'
--group       group to target, defaults to 0

look at her. so simple. so clean. ✨

---

🦋 DESCRIPTION 🦋

the pg_auto_switchover monitor can be used to orchestrate a manual switchover, sometimes also known as a switchover (yes they said it twice, and honestly? correct of them).

when it does this, split-brain is prevented because of intermediary states being used in the Finite State Machine. so the FSM is the bodyguard here. 🫶

the pg_autoctl perform switchover command waits until the switchover is known complete on the monitor, or until the hard-coded 60s timeout has passed. it's giving patient but not that patient.

and here's the thing, bestie: the switchover orchestration is done in the background by the monitor. so even if pg_autoctl perform switchover stops on the timeout, the switchover orchestration continues at the monitor. your command gave up, the monitor did not. main character energy fr fr. 👑

also see pg_autoctl perform failover, a synonym for this command. same vibe, different name.

---

💅 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. (yes, only Citus. everyone else gets one group and they need to be okay with that.)

---

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

---

👑 AUTHOR 👑

Microsoft

---

🎀 COPYRIGHT 🎀

Copyright (c) Microsoft Corporation. All rights reserved.

---

and that's the whole page, bestie, no crumbs left. this was version 2.2, dated Apr 07, 2025 — written down here so you never have to squint at a manpage footer again. go switch something over. slay. 💖✨🦋🌸💅🫶