PG_AUTOCTL ENABLE MONITOR(1)

💖 PG_AUTOCTL ENABLE MONITOR — bestie edition 💖

okay so this is the pg_autoctl enable monitor page from pg_auto_failover, section 1 of the manual, and it's genuinely one of the more underrated glow-ups in the whole toolkit. sit with me, we're doing this together 🫶

---

✨ NAME ✨

pg_autoctl enable monitor — pg_autoctl enable monitor

pg_autoctl enable monitor — Enable a monitor for this node to be orchestrated from

---

🌸 SYNOPSIS 🌸

so here's the vibe: you can disable the pg_auto_failover monitor and then enable it again online, while a pg_autoctl Postgres node is actively running. no shutdown era, we stay live 💅

when is this actually useful, you ask? the main use-cases are when the monitor node has to be replaced, either:

• after a full crash of the previous monitor node 😭
• or for migrating to a new monitor node — hardware replacement, region or zone migration, etc. 🦋

and the usage line goes like this, copy it exactly bestie:

usage: pg_autoctl enable monitor  [ --pgdata --allow-failover ] postgres://autoctl_node@new.monitor.add.ress/pg_auto_failover

--pgdata      path to data directory

---

🎀 OPTIONS 🎀

• --pgdata — where the Postgres node being managed locally lives. defaults to the environment variable PGDATA. also, use --monitor if you want to connect to a monitor from anywhere, rather than using the monitor URI that a local Postgres node managed with pg_autoctl is using. iykyk ✨

---

🌈 ENVIRONMENT 🌈

• PGDATA — Postgres directory location. can be used instead of the --pgdata option. lowkey the same thing, just chiller 💜
• 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. 🍓

---

🔥 EXAMPLES 🔥

not me about to show you the whole arc, start to finish 👑

first, the before pic:

$ pg_autoctl show state
 Name |  Node |      Host:Port |       LSN |   Connection |       Current State |      Assigned State
------+-------+----------------+-----------+--------------+---------------------+--------------------
node1 |     1 | localhost:5501 | 0/4000760 |   read-write |             primary |             primary
node2 |     2 | localhost:5502 | 0/4000760 |    read-only |           secondary |           secondary

then we enable the monitor and the new node registers, which is honestly giving main character energy:

$ pg_autoctl enable monitor --pgdata node3 'postgres://autoctl_node@localhost:5500/pg_auto_failover?sslmode=require'
12:42:07 43834 INFO  Registered node 3 (localhost:5503) with name "node3" in formation "default", group 0, state "wait_standby"
12:42:07 43834 INFO  Successfully registered to the monitor with nodeId 3
12:42:08 43834 INFO  Still waiting for the monitor to drive us to state "catchingup"
12:42:08 43834 WARN  Please make sure that the primary node is currently running `pg_autoctl run` and contacting the monitor.

and the after pic, three nodes deep, absolutely slaying:

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

⚠️ heads up bestie: that WARN line in the middle is doing a lot of work. it's literally telling you to make sure the primary node is currently running pg_autoctl run and contacting the monitor. don't skip it 🙈

---

👑 AUTHOR 👑

Microsoft

---

💜 COPYRIGHT 💜

Copyright (c) Microsoft Corporation. All rights reserved.

---

and that's the whole page, no notes 💅 this was version 2.2, dated Apr 07, 2025, from the PG_AUTOCTL ENABLE MONITOR(1) crew — mwah, go enable your monitor, you got this 🫶✨