PG_AUTOCTL SHOW STATE(1)

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

💖 pg_autoctl show state — a manual page, but make it bestie 💖

okay so this is the page for pg_autoctl show state, part of the pg_auto_failover family. she's the one you call when you want to know what's going on with your nodes, fr fr.

✨ NAME ✨

pg_autoctl show state — pg_autoctl show state

pg_autoctl show state — prints the monitor's state of nodes in a given formation and group. that's it, that's the whole job. she's a gossip and we love her for it 💅

🦋 SYNOPSIS 🦋

this command outputs the current state of the formation and groups registered to the pg_auto_failover monitor:

usage: pg_autoctl show state  [ --pgdata --formation --group ]

--pgdata      path to data directory
--monitor     pg_auto_failover Monitor Postgres URL
--formation   formation to query, defaults to 'default'
--group       group to query formation, defaults to all
--local       show local data, do not connect to the monitor
--watch       display an auto-updating dashboard
--json        output data in the JSON format

🎀 OPTIONS 🎀

the way there are so many of these and every single one matters. okay bestie, let's go:

  • --pgdata — where the Postgres node that's being managed locally lives. defaults to the PGDATA environment variable. if you'd rather connect to a monitor from literally anywhere, use --monitor instead of the monitor URI that a local Postgres node managed with pg_autoctl is using.
  • --monitor — the Postgres URI you use to connect to the monitor. it must use the autoctl_node username and it must target the pg_auto_failover database name. you can show the Postgres URI straight off the monitor node with the command pg_autoctl show uri. iykyk.
  • --formation — lists the events recorded for nodes in the given formation. defaults to default.
  • --group — limits output to a single group in the formation. defaults to including all groups registered in the target formation.
  • --local — prints the local state info without connecting to the monitor. introvert mode 🫶
  • --watch — takes control of the terminal and displays the current state of the system plus the last events from the monitor. the display updates automatically every 500 milliseconds (that's half a second, bestie) and it reacts properly when you change the window size. depending on your terminal window size, a different set of columns is visible in the state part of the output. see pg_autoctl watch.
  • --json — outputs JSON formatted data instead of a table formatted list.

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

👑 DESCRIPTION 👑

the pg_autoctl show state output includes the following columns, and bestie i am going to walk you through every single one because they all eat:

  • Name — Name of the node.
  • Node — Node information. when the formation has a single group (group zero), then this column only contains the nodeId. only Citus formations allow several groups. when using a Citus formation the Node column contains the groupId and the nodeId, separated by a colon, such as 0:1 for the first coordinator node.
  • Host:Port — Hostname and port number used to connect to the node.
  • TLI: LSN — Timeline identifier (TLI) and Postgres Log Sequence Number (LSN). the LSN is the current position in the Postgres WAL stream. this is a hexadecimal number. see pg_lsn for more information. the current timeline is incremented each time a failover happens, or when doing Point In Time Recovery. a node can only reach the secondary state when it is on the same timeline as its primary node.
  • Connection — this output field contains two bits of information. first, the Postgres connection type that the node provides, either read-write or read-only. then the mark ! is added when the monitor has failed to connect to this node, and ? when the monitor didn't connect to the node yet.
  • Reported State — the latest reported FSM state, as reported to the monitor by the pg_autoctl process running on the Postgres node.
  • Assigned State — the assigned FSM state on the monitor. when the assigned state is not the same as the reported start, then the pg_autoctl process running on the Postgres node might have not retrieved the assigned state yet, or might still be implementing the FSM transition from the current state to the assigned state.

🍓 EXAMPLES 🍓

okay now the part where it actually looks cute:

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

$ pg_autoctl show state --local
 Name |  Node |      Host:Port |       TLI: LSN |   Connection |      Reported State |      Assigned State
------+-------+----------------+----------------+--------------+---------------------+--------------------
node1 |     1 | localhost:5501 |   1: 0/4000678 | read-write ? |             primary |             primary

$ pg_autoctl show state --json
[
    {
        "health": 1,
        "node_id": 1,
        "group_id": 0,
        "nodehost": "localhost",
        "nodename": "node1",
        "nodeport": 5501,
        "reported_lsn": "0/4000678",
        "reported_tli": 1,
        "formation_kind": "pgsql",
        "candidate_priority": 50,
        "replication_quorum": true,
        "current_group_state": "primary",
        "assigned_group_state": "primary"
    },
    {
        "health": 1,
        "node_id": 2,
        "group_id": 0,
        "nodehost": "localhost",
        "nodename": "node2",
        "nodeport": 5502,
        "reported_lsn": "0/4000678",
        "reported_tli": 1,
        "formation_kind": "pgsql",
        "candidate_priority": 50,
        "replication_quorum": true,
        "current_group_state": "secondary",
        "assigned_group_state": "secondary"
    },
    {
        "health": 1,
        "node_id": 3,
        "group_id": 0,
        "nodehost": "localhost",
        "nodename": "node3",
        "nodeport": 5503,
        "reported_lsn": "0/4000678",
        "reported_tli": 1,
        "formation_kind": "pgsql",
        "candidate_priority": 50,
        "replication_quorum": true,
        "current_group_state": "secondary",
        "assigned_group_state": "secondary"
    }
]

🌸 AUTHOR 🌸

Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

and that's the whole page bestie 🥹 this was version 2.2, dated Apr 07, 2025, and it lives under the name PG_AUTOCTL SHOW STATE(1). go forth and show state, she's iconic, periodt 💖✨

📦 where this page comes from