pg_autoctl create formation¶
pg_autoctl create formation - Create a new formation on the pg_auto_failover monitor
Synopsis¶
This command registers a new formation on the monitor, with the specified kind:
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
Description¶
A single pg_auto_failover monitor may manage any number of formations, each composed of at least one Postgres service group. This commands creates a new formation so that it is then possible to register Postgres nodes in the new formation.
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
orpg_basebackup
. Defaults to the environment variablePGDATA
.- --monitor
Postgres URI used to connect to the monitor. Must use the
autoctl_node
username and target thepg_auto_failover
database name. It is possible to 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 kindcitus
. At the momentcitus
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 setup 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, 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.