PG_AUTOCTL_PERFORM_SWITCHOVER(1)

💅 pg_autoctl perform switchover 💅

okay bestie, so this one lives in the pg_auto_failover manual section, and it's literally called pg_autoctl perform switchover. Two descriptions, same vibe, no cap:

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

so like. it does the switchover thing. for a formation. and a group. periodt ✨

---

🌸 SYNOPSIS 🌸

this command starts a Postgres switchover orchestration from the pg_auto_switchover monitor, and the usage is giving:

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

---

🦋 DESCRIPTION 🦋

so the pg_auto_switchover monitor can orchestrate a manual switchover — sometimes also known as a switchover, yes they said it twice, iconic of them 💀 — and when it does, split-brain is prevented because the Finite State Machine uses intermediary states. it's giving safe. it's giving responsible. we love a state machine that protects us 🫶

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. so worst case you're standing there for a minute, not forever 💅

and here's the cute part: 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 honestly 👑

also go look at pg_autoctl perform failover, it's a synonym for this command. same energy, different name, iykyk ✨

---

✨ OPTIONS ✨

• --pgdata — where the Postgres node being managed locally lives. defaults to the environment variable PGDATA. and hiiii, use --monitor if you wanna connect to a monitor from anywhere, instead of the monitor URI that a local Postgres node managed with pg_autoctl is using 🌈
• --formation — the formation you're targeting for the operation. defaults to default. it's always default bestie 🙈
• --group — the Postgres group you're targeting for the operation. defaults to 0, and only Citus formations may have more than one group. so if you're not on Citus, it's group 0 and that's that 💀

---

🌈 ENVIRONMENT 🌈

• PGDATA — Postgres directory location. can be used instead of the --pgdata option. same thing, different outfit 💖
• 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 also be a genuinely useful way to select a Postgres version when several are installed on the same system. lowkey a lifesaver when you've got like four Postgres versions fighting on one machine 😭
• PATH — used the usual way, mostly. some entries that the pg_autoctl command searches in the PATH are expected to be found only once, to avoid mistakes with Postgres major versions. so don't be messy with your PATH, bestie, that's how you end up with the wrong major version and a bad time 💅
• PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ... — see the Postgres docs about Environment Variables for details. go read them, they're thorough 👑
• TMPDIR — the pgcopydb command creates all its work files and directories in ${TMPDIR}/pgcopydb, and defaults to /tmp/pgcopydb. yes it says pgcopydb, that's what the original says, we don't question it 🍓
• XDG_CONFIG_HOME — the pg_autoctl command stores its configuration files in the standard place XDG_CONFIG_HOME. see the XDG Base Directory Specification. organized queen behavior ✨
• 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. internal states, tucked away neatly, we stan a tidy filesystem 🎀

---

💜 AUTHOR 💜

Microsoft 🫶

🎀 COPYRIGHT 🎀

Copyright (c) Microsoft Corporation. All rights reserved.

---

and that's the whole page, bestie!! this was version 2.1, dated Jan 18, 2025, from the pg_auto_failover manual. now go switch something over, safely, with your FSM protecting you the whole time 💖✨🦋💅