PG_AUTOCTL_RUN(1)

✨ NAME ✨

pg_autoctl run — bestie, this is the command that just... runs the whole thing. It's the pg_autoctl run of the pg_auto_failover manual, and it's giving Run the pg_autoctl service (monitor or keeper). 💅

---

🌸 SYNOPSIS 🌸

Okay so this command starts up all the processes you need to run either a monitor node or a keeper node — which one it picks depends entirely on the configuration file that belongs to your --pgdata option (or, if you didn't pass that, the PGDATA environment variable). She reads the room and then does her thing. 🦋

usage: pg_autoctl run  [ --pgdata --name --hostname --pgport ]

--pgdata      path to data directory
--name        pg_auto_failover node name
--hostname    hostname used to connect from other nodes
--pgport      PostgreSQL's port number

---

💖 DESCRIPTION 💖

So when you register Postgres nodes to the pg_auto_failover monitor using the pg_autoctl create postgres command, those nodes get registered with metadata — and that metadata is: the node name, the hostname, and the Postgres port. Iconic little trio, no cap. 👑

The node name is mostly used in the logs and in pg_autoctl show state commands, and it's basically there to help human administrators of the formation keep track of who's who. It's the name tag at the party. 🎀

The node hostname and pgport are what other nodes use — including the pg_auto_failover monitor itself — to open a Postgres connection. So like, that's how everybody actually finds each other. 🌈

And here's the cute part: both the node name and the node hostname and port can be changed after the node registration, by using either this command (pg_autoctl run) or the pg_autoctl config set command. Glow-up era fr fr. ✨

---

🎀 OPTIONS 🎀

• --pgdata — Location of the Postgres node being managed locally. 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.
• --name — Node name used on the monitor to refer to this node. The hostname is a technical information, and given Postgres requirements on the HBA setup and DNS resolution (both forward and reverse lookups), IP addresses are often used for the hostname.

The --name option allows using a user-friendly name for your Postgres nodes. 💜 (a cute nickname, basically — your nodes deserve one)

• --hostname — Hostname or IP address (both v4 and v6 are supported) to use from any other node to connect to this node.

When not provided, a default value is computed by running the following algorithm. 🧚

1. We get this machine's "public IP" by opening a connection to the given monitor hostname or IP address. Then we get TCP/IP client address that has been used to make that connection.
2. We then do a reverse DNS lookup on the IP address found in the previous step to fetch a hostname for our local machine.
3. If the reverse DNS lookup is successful , then pg_autoctl does a forward DNS lookup of that hostname.

When the forward DNS lookup response in step 3. is an IP address found in one of our local network interfaces, then pg_autoctl uses the hostname found in step 2. as the default --hostname. Otherwise it uses the IP address found in step 1.

You may use the --hostname command line option to bypass the whole DNS lookup based process and force the local node name to a fixed value. 🫶 (skip the whole detective arc and just tell her who you are)

• --pgport — Postgres port to use, defaults to 5432. ⭐

---

👑 AUTHOR 👑

Microsoft

---

💀 COPYRIGHT 💀

Copyright (c) Microsoft Corporation. All rights reserved.

---

and that's the whole page bestie, you ate 💅

This was pg_autoctl run, from the pg_auto_failover manual, version 2.1, dated Jan 18, 2025. mwah 💖