PG_AUTOCTL(1)

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

💖 PG_AUTOCTL(1) — the pg_auto_failover manual, but make it make sense 💖

okay bestie, sit down, hydrate, because this is the PG_AUTOCTL(1) page from the pg_auto_failover manual set and it's literally the master key to the whole thing. 🔑

✨ NAME ✨

pg_autoctl — pg_autoctl

pg_autoctl — control a pg_auto_failover node 🎀

🌸 SYNOPSIS 🌸

so pg_autoctl ships with all of these commands, no cap:

pg_autoctl
+ create    Create a pg_auto_failover node, or formation
+ drop      Drop a pg_auto_failover node, or formation
+ config    Manages the pg_autoctl configuration
+ show      Show pg_auto_failover information
+ enable    Enable a feature on a formation
+ disable   Disable a feature on a formation
+ get       Get a pg_auto_failover node, or formation setting
+ set       Set a pg_auto_failover node, or formation setting
+ perform   Perform an action orchestrated by the monitor
  activate  Activate a Citus worker from the Citus coordinator
  run       Run the pg_autoctl service (monitor or keeper)
  stop      signal the pg_autoctl service for it to stop
  reload    signal the pg_autoctl for it to reload its configuration
  status    Display the current status of the pg_autoctl service
  help      print help message
  version   print pg_autoctl version

pg_autoctl create
  monitor      Initialize a pg_auto_failover monitor node
  postgres     Initialize a pg_auto_failover standalone postgres node
  coordinator  Initialize a pg_auto_failover citus coordinator node
  worker       Initialize a pg_auto_failover citus worker node
  formation    Create a new formation on the pg_auto_failover monitor

pg_autoctl drop
  monitor    Drop the pg_auto_failover monitor
  node       Drop a node from the pg_auto_failover monitor
  formation  Drop a formation on the pg_auto_failover monitor

pg_autoctl config
  check  Check pg_autoctl configuration
  get    Get the value of a given pg_autoctl configuration variable
  set    Set the value of a given pg_autoctl configuration variable

pg_autoctl show
  uri            Show the postgres uri to use to connect to pg_auto_failover nodes
  events         Prints monitor's state of nodes in a given formation and group
  state          Prints monitor's state of nodes in a given formation and group
  settings       Print replication settings for a formation from the monitor
  standby-names  Prints synchronous_standby_names for a given group
  file           List pg_autoctl internal files (config, state, pid)
  systemd        Print systemd service file for this node

pg_autoctl enable
  secondary    Enable secondary nodes on a formation
  maintenance  Enable Postgres maintenance mode on this node
  ssl          Enable SSL configuration on this node
  monitor      Enable a monitor for this node to be orchestrated from

pg_autoctl disable
  secondary    Disable secondary nodes on a formation
  maintenance  Disable Postgres maintenance mode on this node
  ssl          Disable SSL configuration on this node
  monitor      Disable the monitor for this node

pg_autoctl get
+ node       get a node property from the pg_auto_failover monitor
+ formation  get a formation property from the pg_auto_failover monitor

pg_autoctl get node
  replication-quorum  get replication-quorum property from the monitor
  candidate-priority  get candidate property from the monitor

pg_autoctl get formation
  settings              get replication settings for a formation from the monitor
  number-sync-standbys  get number_sync_standbys for a formation from the monitor

pg_autoctl set
+ node       set a node property on the monitor
+ formation  set a formation property on the monitor

pg_autoctl set node
  metadata            set metadata on the monitor
  replication-quorum  set replication-quorum property on the monitor
  candidate-priority  set candidate property on the monitor

pg_autoctl set formation
  number-sync-standbys  set number-sync-standbys for a formation on the monitor

pg_autoctl perform
  failover    Perform a failover for given formation and group
  switchover  Perform a switchover for given formation and group
  promotion   Perform a failover that promotes a target node

like… look at that tree. it's giving family tree of a royal dynasty. 👑

🦋 DESCRIPTION 🦋

okay so pg_autoctl is the client tool that ships with pg_auto_failover, and its whole job is creating and managing Postgres nodes plus the pg_auto_failover monitor node. 💅

and the way that it's built? it's a big ol' pile of sub-commands, and every single one of them has its own manual page. yes really. go read them. ✨

🌈 HELP 🌈

want the full recursive list of every supported command? (and bestie, it is LONG)

pg_autoctl help

that's it. that's the move. 🫶

⭐ VERSION ⭐

to grab the version of pg_autoctl you're running, hit it with either of these:

pg_autoctl --version
pg_autoctl version

a typical output would be, and I quote:

pg_autoctl version 1.4.2
pg_autoctl extension version 1.4
compiled with PostgreSQL 12.3 on x86_64-apple-darwin16.7.0, compiled by Apple LLVM version 8.1.0 (clang-802.0.42), 64-bit
compatible with Postgres 10, 11, 12, and 13

and if you're a machine and need it as a JSON document, use the --json option:

pg_autoctl --version --json
pg_autoctl version --json

a typical JSON output would be:

{
    "pg_autoctl": "1.4.2",
    "pgautofailover": "1.4",
    "pg_major": "12",
    "pg_version": "12.3",
    "pg_version_str": "PostgreSQL 12.3 on x86_64-apple-darwin16.7.0, compiled by Apple LLVM version 8.1.0 (clang-802.0.42), 64-bit",
    "pg_version_num": 120003
}

so for the record: this is for version 1.4.2 of pg_auto_failover. 🎀 and this particular version of the pg_autoctl client tool has been compiled using libpq for PostgreSQL 12.3, and it's compatible with Postgres 10, 11, 12, and 13. periodt. 💅

💜 ENVIRONMENT 💜

  • PG_AUTOCTL_DEBUG — when this environment variable is set (to anything at all, doesn't matter what) then pg_autoctl allows more commands.
⚠️ bestie. USE. WITH. CARE. ⚠️ this literally opens up abilities to destroy your production clusters. 😭 I am not being dramatic, that's what the page says. treat this env var like a loaded weapon, not a fun little toggle. 🙈

👑 AUTHOR 👑

Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

and that's the whole page, bestie!! 🎉 this was pg_auto_failover version 2.2, dated Apr 07, 2025, from the PG_AUTOCTL(1) manual. slay, stay hydrated, and pls don't set PG_AUTOCTL_DEBUG on prod. 🫶✨💅

📦 where this page comes from