PG_AUTOCTL_CONFIG_SET(1)

📦
version 2.1 · 2 versions
, in fedora 43, fedora 44

💖 PG_AUTOCTL CONFIG SET(1) 💖

okay bestie, welcome to the pg_autoctl config set page from pg_auto_failover, manual section 1 🦋. it's short, it's sweet, it does exactly one thing, and it does it slay. let's get into it.

✨ NAME ✨

pg_autoctl config set — yes that's the name, and also literally what it does, no notes 💅

pg_autoctl config set — set the value of a given pg_autoctl configuration variable 🔥

🌸 SYNOPSIS 🌸

lowkey this page is a little confused about itself, but here's what it says — it says this command prints a pg_autoctl configuration setting (we're all just reading the manpage as written, bestie 🙈):

usage: pg_autoctl config set  [ --pgdata ] [ --json ] section.option [ value ]

--pgdata      path to data directory

so yeah, it's giving "prints" but the whole vibe is "sets". read the DESCRIPTION below, iykyk 🌈

🎀 OPTIONS 🎀

  • --pgdata — where the Postgres node that you're managing locally lives. defaults to the PGDATA environment variable. also, if you use --monitor you can connect to a monitor from literally anywhere, instead of using the monitor URI that a local Postgres node managed with pg_autoctl would use 👑
  • --json — output JSON formatted data. that's it, that's the option, periodt ✨

🦋 ENVIRONMENT 🦋

  • PGDATA — Postgres directory location. you can use this instead of the --pgdata option, if you're feeling lazy (respect 🫶).
  • 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 💜

this command lets you set a pg_autoctl configuration setting to a new value. most settings can be changed and can be reloaded online — no restart, no drama, we love a hot reload 💅.

and then some of those commands can be applied with a pg_autoctl reload command to a process that's already running. iconique.

👑 SETTINGS 👑

here comes the big list, bestie. strap in. this is the main character section fr fr.

pg_autoctl.role

this setting can not be changed. it's either monitor or keeper, and the rest of the configuration file is read depending on this value. it's the vibe-setter of the whole config, and it's not taking suggestions 💀

pg_autoctl.monitor

URI of the pg_autoctl monitor Postgres service. can be changed with a reload ✅.

to register an existing node to a new monitor, use pg_autoctl disable monitor and then pg_autoctl enable monitor. (not me reminding you to do both steps 🙈)

pg_autoctl.formation

the formation this node has been registered to. changing this setting is not supported — don't try it, she will not cooperate 🚫.

pg_autoctl.group

the group this node has been registered in. changing this setting is not supported either 🚫.

pg_autoctl.name

the name of the node as the monitor knows it, and as it's listed in pg_autoctl show state. can be changed with a reload ✨.

pg_autoctl.hostname

hostname or IP address of the node, as known to the monitor. can be changed with a reload ✨.

pg_autoctl.nodekind

this setting can not be changed, and it depends on the command that was used to create this pg_autoctl node. it's basically set at birth 👶.

postgresql.pgdata

the directory where the managed Postgres instance is to be created (or found) and managed. can't be changed. nope. not happening. 🚫

postgresql.pg_ctl

path to the pg_ctl tool used to manage this Postgres instance. the absolute path depends on the major version of Postgres and looks like /usr/lib/postgresql/13/bin/pg_ctl when you're using a debian or ubuntu OS 🐧.

can be changed after a major upgrade of Postgres ✅.

postgresql.dbname

name of the database used to connect to Postgres. it can be changed, but then it must be changed manually on the monitor's pgautofailover.formation table with a SQL command. so like, technically yes, but do it in both places or chaos 🌀.

WARNING: when using pg_auto_failover enterprise edition with Citus support, this is the database where pg_autoctl maintains the list of Citus nodes on the coordinator. using the same database name as your application that uses Citus is then crucial. do not fumble this one bestie 😭

postgresql.host

hostname to use in connection strings when connecting from the local pg_autoctl process to the local Postgres database. defaults to using the Operating System default value for the Unix Domain Socket directory — either /tmp, or /var/run/postgresql when using debian or ubuntu 🐧.

can be changed with a reload ✅.

postgresql.port

port on which Postgres should be managed. can be changed offline, between a pg_autoctl stop and a subsequent pg_autoctl start. so like, stop first. please. 🙏

postgresql.listen_addresses

the value to set to the Postgres parameter of the same name. at the moment pg_autoctl only supports a single address for this parameter 🎯.

postgresql.auth_method

the authentication method to use when editing HBA rules — this is what allows the Postgres nodes of a formation to connect to each other, and to the monitor, and it lets the monitor connect to the nodes 🤝.

can be changed online with a reload, but actually adding new HBA rules requires a restart of the "node-active" service. so, reload gets you partway, restart finishes the job 💅.

postgresql.hba_level

this setting reflects the choice of --skip-pg-hba or --pg-hba-lan that was used when creating this pg_autoctl node. can be changed with a reload — though heads up, the HBA rules that were previously added will not get removed 🫠.

ssl.active, ssl.sslmode, ssl.cert_file, ssl.key_file, etc

please use the command pg_autoctl enable ssl or pg_autoctl disable ssl to manage the SSL settings in the ssl section of the configuration. using those commands, the settings can be changed online 🔒✨.

replication.maximum_backup_rate

used as a parameter to pg_basebackup, defaults to 100M. can be changed with a reload. changing this value does not affect an already running pg_basebackup command — it's not retroactive, bestie 💀.

limiting the bandwidth used by pg_basebackup makes the operation slower, and still has the advantage of limiting the impact on the disks of the primary server. so it's a trade-off, and a valid one 💖.

replication.backup_directory

target location of the pg_basebackup command used by pg_autoctl when creating a secondary node. when it's done fetching the data over the network, pg_autoctl uses the rename(2) system-call to rename the temporary download location to the target PGDATA location 📦➡️📂.

the rename(2) system-call is known to be atomic when both the source and the target of the operation are using the same file system / mount point ⚛️.

can be changed online with a reload, and it will not affect already running pg_basebackup sub-processes.

replication.password

used as a parameter in the connection string to the upstream Postgres node. the "replication" connection uses the password set-up in the pg_autoctl configuration file 🔑.

changing the replication.password of a pg_autoctl configuration has no effect on the Postgres database itself. the password must match what the Postgres upstream node expects, which can be set with the following SQL command run on the upstream server (primary or other standby node):

alter user pgautofailover_replicator password 'h4ckm3m0r3';

the replication.password can be changed online with a reload, but requires restarting the Postgres service to be activated. Postgres only reads the primary_conninfo connection string at start-up, up to and including Postgres 12. with Postgres 13 and following, it is possible to reload this Postgres parameter ✅.

timeout.network_partition_timeout

timeout (in seconds) that pg_autoctl waits before deciding that it is on the losing side of a network partition. when pg_autoctl fails to connect to the monitor, and when the local Postgres instance pg_stat_replication system view is empty, and after this many seconds have passed, then pg_autoctl demotes itself 🫡.

can be changed with a reload ✅.

timeout.prepare_promotion_catchup

currently not used in the source code. can be changed with a reload 💀.

timeout.prepare_promotion_walreceiver

currently not used in the source code. can be changed with a reload 💀.

timeout.postgresql_restart_failure_timeout

when pg_autoctl fails to start Postgres for at least this duration from the first attempt, then it starts reporting that Postgres is not running to the monitor, which might then decide to implement a failover 🚨.

can be changed with a reload ✅.

timeout.postgresql_restart_failure_max_retries

when pg_autoctl fails to start Postgres for at least this many times, then it starts reporting that Postgres is not running to the monitor, which them might decide to implement a failover 🚨.

can be changed with a reload ✅.

🌈 AUTHOR 🌈

Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

and that's the whole page bestie, you ate that 💅✨. this was version 2.1, dated Jan 18, 2025, from the pg_auto_failover crew — go forth and configure responsibly, mwah 🫶💖

📦 where this page comes from