PG_AUTOCTL CREATE FORMATION(1)

💖 PG_AUTOCTL CREATE FORMATION(1) 💖

okay bestie, welcome to the pg_auto_failover manual, and specifically the page for pg_autoctl create formation. buckle up, this one's a lil niche but it's lowkey iconic ✨

---

🌸 NAME 🌸

pg_autoctl create formation — pg_autoctl create formation

pg_autoctl create formation — Create a new formation on the pg_auto_failover monitor

---

✨ SYNOPSIS ✨

so basically this command registers a brand new formation on the monitor, and you tell it what kind it is:

usage: pg_autoctl create formation  [ --pgdata --monitor --formation --kind --dbname  --with-secondary --without-secondary ]

--pgdata      path to data directory
--monitor     pg_auto_failover Monitor Postgres URL
--formation   name of the formation to create
--kind        formation kind, either "pgsql" or "citus"
--dbname      name for postgres database to use in this formation
--enable-secondary     create a formation that has multiple nodes that can be
                       used for fail over when others have issues
--disable-secondary    create a citus formation without nodes to fail over to
--number-sync-standbys minimum number of standbys to confirm write

(not me noticing the usage line says --with-secondary / --without-secondary / --number-sync-standbys while the actual options below are --enable-secondary / --disable-secondary / --number-sync-standby… iykyk, i'm just reporting what the page says fr fr 💀)

---

🦋 DESCRIPTION 🦋

A single pg_auto_failover monitor may manage any number of formations, and each one is composed of at least one Postgres service group. This command creates a new formation, so that afterwards it's actually possible to register Postgres nodes in the new formation. it's giving "build the container before you fill it" energy 🎀

---

💅 OPTIONS 💅

The following options are available to pg_autoctl create formation:

• --pgdata — Location where to initialize a Postgres database cluster, using either pg_ctl initdb or pg_basebackup. Defaults to the environment variable PGDATA.
• --monitor — 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 using the command pg_autoctl show uri.
• --formation — Name of the formation to create.
• --kind — A pg_auto_failover formation could be of kind pgsql or of kind citus. At the moment citus formation kinds are not managed in the Open Source version of pg_auto_failover. 😭
• --dbname — Name of the database to use in the formation, mostly useful to formation kinds citus where the Citus extension is only installed in a single target database.
• --enable-secondary — The formation to be created allows using standby nodes. Defaults to true. Mostly useful for Citus formations.
• --disable-secondary — See --enable-secondary above.
• --number-sync-standby — Postgres streaming replication uses synchronous_standby_names to set up how many standby nodes should have received a copy of the transaction data. When using pg_auto_failover this setup is handled at the formation level.

Defaults to zero when creating the first two Postgres nodes in a formation in the same group. When set to zero, pg_auto_failover uses synchronous replication only when a standby node is available: the idea is to allow failover, and this setting does not allow proper HA for Postgres.

When adding a third node that participates in the quorum (one primary, two secondaries), the setting is automatically changed from zero to one. 👑

---

🌈 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.

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.

---

🫶 AUTHOR 🫶

Microsoft

---

👑 COPYRIGHT 👑

Copyright (c) Microsoft Corporation. All rights reserved.

---

k that's the whole page bestie, go forth and create formations 💖✨

pg_auto_failover version 2.2, dated Apr 07, 2025 — and that's the PG_AUTOCTL CREATE FORMATION(1) page, done and dusted, no cap 🎀💜🦋