PG_AUTOCTL DROP NODE(1)

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

🫶 PG_AUTOCTL DROP NODE 💅

okay bestie so this is a page from the pg_auto_failover manual — it's PG_AUTOCTL DROP NODE(1), and it's literally the whole entire glow-up guide for kicking a node out of your cluster. no cap, it's giving "it's not you, it's the monitor". 🌸

✨ NAME ✨

pg_autoctl drop node — pg_autoctl drop node

pg_autoctl drop node — drop a node from the pg_auto_failover monitor 🦋

✨ SYNOPSIS ✨

so this command drops a Postgres node from the pg_auto_failover monitor, like:

usage: pg_autoctl drop node [ [ [ --pgdata ] [ --destroy ] ] | [ --monitor [ [ --hostname --pgport ] | [ --formation --name ] ] ] ]

--pgdata      path to data directory
--monitor     pg_auto_failover Monitor Postgres URL
--formation   pg_auto_failover formation
--name        drop the node with the given node name
--hostname    drop the node with given hostname and pgport
--pgport      drop the node with given hostname and pgport
--destroy     also destroy Postgres database
--force       force dropping the node from the monitor
--wait        how many seconds to wait, default to 60

✨ DESCRIPTION ✨

bestie, there are two modes of operations baked into the pg_autoctl drop node command. two!! modes!! iconic. 👑

so, mode one: when you're removing a node that still exists, you can hit it with pg_autoctl drop node --destroy and it removes the node from the monitor and deletes the local Postgres instance entirely. full send. bye forever. 💀

mode two: when you're removing a node that doesn't exist physically anymore, or when the VM that used to host the node has been lost entirely (gone, reduced to atoms 😭), you use either the pair of options --hostname and --pgport, or the pair of options --formation and --name, to match the node registration record on the monitor database — and get it removed from the known list of nodes on the monitor.

then there's --force, which you can use when the target node to remove does not exist anymore. when a node has been lost entirely, it's not going to be able to finish the procedure itself, so you get to just... tell the monitor what's up. inform it. spill the tea. 🫖

✨ OPTIONS ✨

  • --pgdata — where the Postgres node being managed locally lives. defaults to the environment variable PGDATA. use --monitor to connect to a monitor from anywhere, rather than the monitor URI used by a local Postgres node managed with pg_autoctl.
  • --monitor — the Postgres URI used to connect to the monitor. it must use the autoctl_node username and target the pg_auto_failover database name. btw you can show the Postgres URI from the monitor node using the command pg_autoctl show uri. handy fr fr.
  • --hostname — hostname of the Postgres node to remove from the monitor. use either --name or --hostname --pgport, but not both. pick a lane bestie.
  • --pgport — port of the Postgres node to remove from the monitor. use either --name or --hostname --pgport, but not both. same deal.
  • --name — name of the node to remove from the monitor. use either --name or --hostname --pgport, but not both. okay we get it 💅
  • --destroy — by default the pg_autoctl drop monitor commands does not remove the Postgres database for the monitor. when using --destroy, the Postgres installation is also deleted. so like, actually gone gone.
  • --force — by default a node is expected to reach the assigned state DROPPED when it is removed from the monitor, and has the opportunity to implement clean-up actions. when the target node to remove is not available anymore, it is possible to use the option --force to immediately remove the node from the monitor.
  • --wait — how many seconds to wait for the node to be dropped entirely. the command stops when the target node is not to be found on the monitor anymore, or when the timeout has elapsed, whichever comes first. the value 0 (zero) disables the timeout and disables waiting entirely, making the command async. ✨

🌈 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.
  • PG_AUTOCTL_NODE_NAME — node name to register to the monitor, can be used instead of the --name option.
  • PG_AUTOCTL_REPLICATION_QUORUM — can be used instead of the --replication-quorum option.
  • PG_AUTOCTL_CANDIDATE_PRIORITY — can be used instead of the --candidate-priority 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 be a useful way to select a Postgres version when several are installed on the same system.
  • PATH — used the usual way mostly. some entries that are searched in the PATH by the pg_autoctl command are expected to be found only once, to avoid mistakes with Postgres major versions. 👀
  • PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ... — see the Postgres docs about Environment Variables for details.
  • TMPDIR — the pgcopydb command creates all its work files and directories in ${TMPDIR}/pgcopydb, and defaults to /tmp/pgcopydb.
  • 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 🎀

watch this, it's giving a full little story:

$ pg_autoctl drop node --destroy --pgdata ./node3
17:52:21 54201 INFO  Reaching assigned state "secondary"
17:52:21 54201 INFO  Removing node with name "node3" in formation "default" from the monitor
17:52:21 54201 WARN  Postgres is not running and we are in state secondary
17:52:21 54201 WARN  Failed to update the keeper's state from the local PostgreSQL instance, see above for details.
17:52:21 54201 INFO  Calling node_active for node default/4/0 with current state: PostgreSQL is running is false, sync_state is "", latest WAL LSN is 0/0.
17:52:21 54201 INFO  FSM transition to "dropped": This node is being dropped from the monitor
17:52:21 54201 INFO  Transition complete: current state is now "dropped"
17:52:21 54201 INFO  This node with id 4 in formation "default" and group 0 has been dropped from the monitor
17:52:21 54201 INFO  Stopping PostgreSQL at "/Users/dim/dev/MS/pg_auto_failover/tmux/node3"
17:52:21 54201 INFO  /Applications/Postgres.app/Contents/Versions/12/bin/pg_ctl --pgdata /Users/dim/dev/MS/pg_auto_failover/tmux/node3 --wait stop --mode fast
17:52:21 54201 INFO  /Applications/Postgres.app/Contents/Versions/12/bin/pg_ctl status -D /Users/dim/dev/MS/pg_auto_failover/tmux/node3 [3]
17:52:21 54201 INFO  pg_ctl: no server running
17:52:21 54201 INFO  pg_ctl stop failed, but PostgreSQL is not running anyway
17:52:21 54201 INFO  Removing "/Users/dim/dev/MS/pg_auto_failover/tmux/node3"
17:52:21 54201 INFO  Removing "/Users/dim/dev/MS/pg_auto_failover/tmux/config/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node3/pg_autoctl.cfg"

the FSM transition to "dropped" line?? main character energy. ✨

👑 AUTHOR 👑

Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

okay that's the whole page bestie, go forth and drop nodes responsibly 🫶✨ this was manual page version 2.2, dated Apr 07, 2025, and it lives in the pg_auto_failover manual, PG_AUTOCTL DROP NODE(1). slay, periodt. 💅🌸

📦 where this page comes from