PG_AUTOCTL WATCH(1)

💖 PG_AUTOCTL WATCH(1) 💖

okay bestie, so this one lives in the pg_auto_failover manual — it's the page for pg_autoctl watch — and it is genuinely one of the most fun commands in the whole toolkit. it's giving live dashboard, it's giving main character energy, and i'm about to walk you through every single bit of it. no cap. 🦋

---

✨ NAME ✨

pg_autoctl watch — pg_autoctl watch

pg_autoctl watch — Display an auto-updating dashboard 🌈

---

🎀 SYNOPSIS 🎀

so this command outputs the events that the pg_auto_failover events records about state changes of the pg_auto_failover nodes managed by the monitor:

usage: pg_autoctl watch  [ --pgdata --formation --group ]

--pgdata      path to data directory
--monitor     show the monitor uri
--formation   formation to query, defaults to 'default'
--group       group to query formation, defaults to all
--json        output data in the JSON format

---

💅 OPTIONS 💅

• --pgdata — where the Postgres node that's being managed locally actually lives. defaults to the environment variable PGDATA. and listen — if you wanna connect to a monitor from literally anywhere instead of using the monitor URI that a local Postgres node managed with pg_autoctl is using, just use --monitor instead. periodt. 💜
• --monitor — the Postgres URI you use to connect to the monitor. it must use the autoctl_node username and target the pg_auto_failover database name, no exceptions bestie. and psst — you can show the Postgres URI straight from the monitor node using the command pg_autoctl show uri. iconic. 🫶
• --formation — lists the events recorded for nodes in the given formation. defaults to default. 🌸
• --group — limits the output to a single group in the formation. defaults to including all groups registered in the target formation. slay. ⭐

---

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

okay so the pg_autoctl watch output is divided into 3 sections. let's break them down one by one, bestie.

🌟 Section One: the header line 🌟

the first section is a single header line. it includes the name of the currently selected formation, the formation replication setting Number Sync Standbys, and then — all the way over in the right most position — the current time. cute, right? 🕐

🌟 Section Two: one line per node 🌟

the second section displays one line per node, and each line contains a list of columns that describe the current state for the node. this list can include the following columns, and which columns are actually part of the output depends on the terminal window size. this choice is dynamic and it changes if your terminal window size changes. so yes, resize your terminal and watch it shift, it's lowkey mesmerizing. 💫

• Name — Name of the node. 🍓
• Node, or Id — 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. 💀 (not me thinking about coordinator nodes at 2am)

• Last Report, or Report — the time interval between now and the last known time when a node has reported to the monitor, using the node_active protocol.

this value is expected to stay under 2s or abouts, and is known to increment when either the pg_autoctl run service is not running, or when there is a network split. 🙈

• Last Check, or Check — the time interval between now and the last known time when the monitor could connect to a node's Postgres instance, via its health check mechanism.

this value is known to increment when either the Postgres service is not running on the target node, when there is a network split, or when the internal machinery (the health check worker background process) implements jitter. 😭

• 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 current 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. 🌸

🌟 Section Three: the events 🌟

the third and last section lists the most recent events that the monitor has registered — and the more recent event is found at the bottom of the screen. so scroll down, bestie, the freshest tea is at the bottom. 🍵

to quit the command hit either the F1 key or the q key. that's it. you're free. 🕊️

---

💜 AUTHOR 💜

Microsoft

---

🫶 COPYRIGHT 🫶

Copyright (c) Microsoft Corporation. All rights reserved.

---

and that's the whole page, bestie!! we did it!! 💖 this was version 2.2, dated Apr 07, 2025, from the pg_auto_failover manual — go forth and watch your nodes like the main character you are. mwah. 💅✨🎀🦋🌸