PG_AUTOCTL_CREATE_FORMATION(1)

💖 PG_AUTOCTL CREATE FORMATION(1) 💖

okay bestie, so this is the pg_autoctl create formation page from the pg_auto_failover manual — and yeah, we're in section 1 of the manual, the classic "user commands" girlies. let's get into it 🫶

---

✨ NAME ✨

pg_autoctl create formation — pg_autoctl create formation

pg_autoctl create formation — spin up a brand new formation on the pg_auto_failover monitor 🎀

---

🌸 SYNOPSIS 🌸

this command registers a new formation on the monitor, with the kind you picked:

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

no cap, that's the whole vibe right there 💅

---

🦋 DESCRIPTION 🦋

one single pg_auto_failover monitor can manage literally any number of formations, and each formation is made up of at least one Postgres service group. this command creates a new formation so that, once it exists, you can go ahead and register Postgres nodes into it. it's giving "set up the group chat before you add the members" energy 🍓

---

💅 OPTIONS 💅

the following options are available to pg_autoctl create formation:

• --pgdata — where you wanna initialize a Postgres database cluster, using either pg_ctl initdb or pg_basebackup. defaults to the environment variable PGDATA. main character location energy 📍
• --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. pro tip: you can show the Postgres URI from the monitor node with pg_autoctl show uri. 🔥
• --formation — the name of the formation to create. name her, bestie ✨
• --kind — a pg_auto_failover formation can be kind pgsql or kind citus. as of right now, citus formation kinds are not managed in the Open Source version of pg_auto_failover. iykyk 🫶
• --dbname — the name of the database to use in the formation, mostly useful for formation kinds citus, where the Citus extension is only installed in a single target database. one database, one destiny 💜
• --enable-secondary — the formation being created allows using standby nodes. defaults to true. mostly useful for Citus formations. 😌
• --disable-secondary — see --enable-secondary above. same thing, opposite direction 💀
• --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 you're using pg_auto_failover, this setup is handled at the formation level instead.
  • 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 — 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. glow-up, automatic ✨

---

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

these env vars are lowkey the "instead of typing the flag" besties. use them, they're iconic 💖

---

👑 AUTHOR 👑

Microsoft

---

💜 COPYRIGHT 💜

Copyright (c) Microsoft Corporation. All rights reserved.

---

and that's the whole page, bestie!! this is from pg_auto_failover version 2.1, dated Jan 18, 2025, and it lives in section 1 of the manual as PG_AUTOCTL CREATE FORMATION(1). periodt. go create a formation, you've got this 💅🎀🦋