PG_AUTOCTL_CREATE_POSTGRES(1)

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

🌸 PG_AUTOCTL CREATE POSTGRES(1) 🌸

okay so bestie, welcome to the pg_auto_failover manual — this is the page for pg_autoctl create postgres, and no cap, it's a whole vibe. grab a strawberry 🍓, sit down, we're doing this together.

✨ NAME ✨

pg_autoctl create postgres — yeah she's literally named that twice, it's giving main character energy

pg_autoctl create postgres — Initialize a pg_auto_failover postgres node 💅

🎀 SYNOPSIS 🎀

So the command pg_autoctl create postgres initializes a standalone Postgres node into a pg_auto_failover monitor. Then the monitor is handling auto-failover for this Postgres node — but only as soon as a secondary has been registered too, and is known to be healthy. periodt. no secondary, no party 🙈

usage: pg_autoctl create postgres

  --pgctl           path to pg_ctl
  --pgdata          path to data directory
  --pghost          PostgreSQL's hostname
  --pgport          PostgreSQL's port number
  --listen          PostgreSQL's listen_addresses
  --username        PostgreSQL's username
  --dbname          PostgreSQL's database name
  --name            pg_auto_failover node name
  --hostname        hostname used to connect from the other nodes
  --formation       pg_auto_failover formation
  --monitor         pg_auto_failover Monitor Postgres URL
  --auth            authentication method for connections from monitor
  --skip-pg-hba     skip editing pg_hba.conf rules
  --pg-hba-lan      edit pg_hba.conf rules for --dbname in detected LAN
  --ssl-self-signed setup network encryption using self signed certificates (does NOT protect against MITM)
  --ssl-mode        use that sslmode in connection strings
  --ssl-ca-file     set the Postgres ssl_ca_file to that file path
  --ssl-crl-file    set the Postgres ssl_crl_file to that file path
  --no-ssl          don't enable network encryption (NOT recommended, prefer --ssl-self-signed)
  --server-key      set the Postgres ssl_key_file to that file path
  --server-cert     set the Postgres ssl_cert_file to that file path
  --candidate-priority    priority of the node to be promoted to become primary
  --replication-quorum    true if node participates in write quorum
  --maximum-backup-rate   maximum transfer rate of data transferred from the server during initial sync

💖 DESCRIPTION 💖

Three different modes of initialization are supported by this command, corresponding to as many implementation strategies. (yes bestie, they said "three" and then listed four — we are simply not going to address that, we love a chaotic queen 👑)

  1. Initialize a primary node from scratch 🦋

This happens when --pgdata (or the environment variable PGDATA) points to an non-existing or empty directory. Then the given --hostname is registered to the pg_auto_failover --monitor as a member of the --formation.

The monitor answers to the registration call with a state to assign to the new member of the group, either SINGLE or WAIT_STANDBY. When the assigned state is SINGLE, then pg_autoctl create postgres proceeds to initialize a new PostgreSQL instance. slay. ✨

  1. Initialize an already existing primary server 🌈

This happens when --pgdata (or the environment variable PGDATA) points to an already existing directory that belongs to a PostgreSQL instance. The standard PostgreSQL tool pg_controldata is used to recognize whether the directory belongs to a PostgreSQL instance.

In that case, the given --hostname is registered to the monitor in the tentative SINGLE state. When the given --formation and --group is currently empty, then the monitor accepts the registration and the pg_autoctl create prepares the already existing primary server for pg_auto_failover. 🫶

  1. Initialize a secondary node from scratch 💜

This happens when --pgdata (or the environment variable PGDATA) points to a non-existing or empty directory, and when the monitor registration call assigns the state WAIT_STANDBY in step 1.

In that case, the pg_autoctl create command steps through the initial states of registering a secondary server, which includes preparing the primary server PostgreSQL HBA rules and creating a replication slot. the way that it just… does all that? iconic.

When the command ends successfully, a PostgreSQL secondary server has been created with pg_basebackup and is now started, catching-up to the primary server. 🔥

  1. Initialize a secondary node from an existing data directory 🧚

When the data directory pointed to by the option --pgdata or the environment variable PGDATA already exists, then pg_auto_failover verifies that the system identifier matches the one of the other nodes already existing in the same group.

The system identifier can be obtained with the command pg_controldata. All nodes in a physical replication setting must have the same system identifier, and so in pg_auto_failover all the nodes in a same group have that constraint too. it's not a suggestion bestie, it's a requirement. 💀

When the system identifier matches the already registered system identifier of other nodes in the same group, then the node is set-up as a standby and Postgres is started with the primary conninfo pointed at the current primary. ⭐

The --auth option allows setting up authentication method to be used when monitor node makes a connection to data node with pgautofailover_monitor user. As with the pg_autoctl create monitor command, you could use --auth trust when playing with pg_auto_failover at first and consider something production grade later. ngl, "later" is doing a LOT of heavy lifting in that sentence 😭

Also, consider using --skip-pg-hba if you already have your own provisioning tools with a security compliance process. respect the process, bestie. 💅

See Security settings for pg_auto_failover for notes on .pgpass 🔑

heads up: --auth trust is for playing around, fr fr. it is NOT the production vibe. and --ssl-self-signed does NOT protect against MITM — the page says it right there in the flag description, so don't come for me. 🙈

✨ OPTIONS ✨

okay bestie, here's the full menu of flags for pg_autoctl create postgres. there are a LOT of them. hydrate, get comfy, we're going through every single one 💅

  • --pgctl — the path to the pg_ctl tool for whichever PostgreSQL version you wanna use.

defaults to the pg_ctl that's found in your PATH when there's exactly ONE pg_ctl entry in there (no ambiguity, no drama). check your setup with which -a pg_ctl.

on RPM-based distros like RHEL or CentOS, the path is usually /usr/pgsql-13/bin/pg_ctl for Postgres 13.

on debian-based distros like debian or ubuntu, it's usually /usr/lib/postgresql/13/bin/pg_ctl for Postgres 13. those distros also ship the package postgresql-common, which provides /usr/bin/pg_config. and guess what — pg_autoctl can use that tool automatically to discover the default Postgres version on your setup. iconic ✨

  • --pgdata — where to init a Postgres database cluster, using either pg_ctl initdb or pg_basebackup. defaults to the env var PGDATA.
  • --pghost — the hostname to use when connecting to the local Postgres instance from the pg_autoctl process. by default this field is left blank in the connection string, which lets you use Unix Domain Sockets with the default path compiled into your libpq version (usually provided by the OS). that path is /var/run/postgresql on debian or ubuntu.
  • --pgport — the Postgres port to use. defaults to 5432.
  • --listen — PostgreSQL's listen_addresses to set up. rn only ONE address is supported in this command line option, so pick your fave 🙈
  • --username — PostgreSQL's username, used when connecting to the local Postgres instance to manage it.
  • --dbname — PostgreSQL's database name for your application. defaults to being the same as --username, or to postgres when neither of those options is used.
  • --name — the node name used on the monitor to refer to this node. the hostname is a technical piece of info, and given Postgres requirements around HBA setup and DNS resolution (both forward AND reverse lookups), IP addresses often end up being used for the hostname.

so the --name option lets you use a user-friendly name for your Postgres nodes instead. main character energy for your nodes, fr fr 👑

  • --hostname — the hostname or IP address (both v4 and v6 are supported) that other nodes use to connect to this node.

when it's not provided, a default value gets computed by running this algorithm:

  1. we get this machine's "public IP" by opening a connection to the given monitor hostname or IP address. then we grab the TCP/IP client address that was 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 succeeds, 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 can also just use the --hostname command line option to bypass this whole DNS lookup process and force the local node name to a fixed value. no cap, sometimes you just wanna skip the side quest 😌

  • --formation — the formation to register the node into on the monitor. defaults to the default formation, which is automatically created in the monitor by the pg_autoctl create monitor command.
  • --monitor — the Postgres URI used to connect to the monitor. must use the autoctl_node username and target the pg_auto_failover database name. you can show the Postgres URI from the monitor node with the command pg_autoctl show uri.
  • --auth — the authentication method used by pg_autoctl when editing the Postgres HBA file to open connections to other nodes. there's no default value, the user has to provide it. the value --trust is only a good choice for testing and evaluation of pg_auto_failover — see Security settings for pg_auto_failover for more info.
bestie pls, do NOT ship --trust to prod. it's giving "I left the front door open" 💀
  • --skip-pg-hba — when this is used, pg_autoctl refrains from any editing of the Postgres HBA file. but heads up: editing the HBA file is still needed so other nodes can connect using either read privileges or replication streaming privileges.

when --skip-pg-hba is used, pg_autoctl still outputs the HBA entries it needs in the logs — it just skips editing the HBA file itself.

  • --pg-hba-lan — when this is used, pg_autoctl determines the local IP address used to connect to the monitor, retrieves its netmask, and uses that to compute your local area network CIDR. this CIDR then gets opened for connections in the Postgres HBA rules.

for instance, when the monitor resolves to 192.168.0.1 and your local Postgres node uses an interface with IP address 192.168.0.2/255.255.255.0 to connect to the monitor, then the LAN CIDR is computed to be 192.168.0.0/24. math ate that 🔥

  • --candidate-priority — sets this node's replication setting for candidate priority to the given value (between 0 and 100) at node registration on the monitor. defaults to 50.
  • --replication-quorum — sets this node's replication setting for replication quorum to the given value (either true or false) at node registration on the monitor. defaults to true, which enables synchronous replication.
  • --maximum-backup-rate — sets the maximum transfer rate of data transferred from the server during initial sync. this is used by pg_basebackup. defaults to 100M.
  • --run — immediately run the pg_autoctl service after having created this node. no chill, straight to business 🏃‍♀️
  • --ssl-self-signed — generate SSL self-signed certificates to provide network encryption.
this does not protect against man-in-the-middle kinds of attacks. it's encryption, not a bodyguard 🫶

see Security settings for pg_auto_failover for more about the SSL settings.

  • --ssl-mode — the SSL Mode used by pg_autoctl when connecting to other nodes, including when connecting for streaming replication.
  • --ssl-ca-file — set the Postgres ssl_ca_file to that file path.
  • --ssl-crl-file — set the Postgres ssl_crl_file to that file path.
  • --no-ssl — don't enable network encryption.
this is not recommended, prefer --ssl-self-signed instead 💖
  • --server-key — set the Postgres ssl_key_file to that file path.
  • --server-cert — set the Postgres ssl_cert_file to that file path.

🌈 ENVIRONMENT 🌈

these are the env vars that pg_autoctl vibes with:

  • 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 also 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 pg_autoctl searches for in the PATH are expected to be found only ONCE, to avoid mistakes with Postgres major versions. so like, don't have three of them, bestie 😭
  • PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ... — see the Postgres docs about Environment Variables for the deets.
  • 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 state files in the standard place XDG_DATA_HOME, which defaults to ~/.local/share. see the XDG Base Directory Specification.

💜 AUTHOR 💜

Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

and that's the whole page, bestie!! you made it to the end, so proud of you 🥹 this was pg_autoctl create postgres from pg_autoctl version 2.1, dated Jan 18, 2025. go forth and create some iconic Postgres nodes, you've got this 💅✨🌸

📦 where this page comes from