.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PG_AUTOCTL CREATE FORMATION" "1" "Nov 06, 2022" "2.0" "pg_auto_failover"
.SH NAME
pg_autoctl create formation \- pg_autoctl create formation
.sp
pg_autoctl create formation \- Create a new formation on the pg_auto_failover
monitor
.SH SYNOPSIS
.sp
This command registers a new formation on the monitor, with the specified
kind:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
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.
.SH OPTIONS
.sp
The following options are available to \fBpg_autoctl create formation\fP:
.INDENT 0.0
.TP
.B  \-\-pgdata
Location where to initialize a Postgres database cluster, using either
\fBpg_ctl initdb\fP or \fBpg_basebackup\fP\&. Defaults to the environment
variable \fBPGDATA\fP\&.
.TP
.B  \-\-monitor
Postgres URI used to connect to the monitor. Must use the \fBautoctl_node\fP
username and target the \fBpg_auto_failover\fP database name. It is possible
to show the Postgres URI from the monitor node using the command
\fI\%pg_autoctl show uri\fP\&.
.TP
.B  \-\-formation
Name of the formation to create.
.TP
.B  \-\-kind
A pg_auto_failover formation could be of kind \fBpgsql\fP or of kind
\fBcitus\fP\&. At the moment \fBcitus\fP formation kinds are not managed in the
Open Source version of pg_auto_failover.
.TP
.B  \-\-dbname
Name of the database to use in the formation, mostly useful to formation
kinds \fBcitus\fP where the Citus extension is only installed in a single
target database.
.TP
.B  \-\-enable\-secondary
The formation to be created allows using standby nodes. Defaults to
\fBtrue\fP\&. Mostly useful for Citus formations.
.TP
.B  \-\-disable\-secondary
See \fB\-\-enable\-secondary\fP above.
.TP
.B  \-\-number\-sync\-standby
Postgres streaming replication uses \fBsynchronous_standby_names\fP 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.
.sp
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.
.sp
When adding a third node that participates in the quorum (one primary, two
secondaries), the setting is automatically changed from zero to one.
.UNINDENT
.SH ENVIRONMENT
.sp
PGDATA
.INDENT 0.0
.INDENT 3.5
Postgres directory location. Can be used instead of the \fB\-\-pgdata\fP
option.
.UNINDENT
.UNINDENT
.sp
PG_AUTOCTL_MONITOR
.INDENT 0.0
.INDENT 3.5
Postgres URI to connect to the monitor node, can be used instead of the
\fB\-\-monitor\fP option.
.UNINDENT
.UNINDENT
.sp
XDG_CONFIG_HOME
.INDENT 0.0
.INDENT 3.5
The pg_autoctl command stores its configuration files in the standard
place XDG_CONFIG_HOME. See the \fI\%XDG Base Directory Specification\fP\&.
.UNINDENT
.UNINDENT
.sp
XDG_DATA_HOME
.INDENT 0.0
.INDENT 3.5
The pg_autoctl command stores its internal states files in the standard
place XDG_DATA_HOME, which defaults to \fB~/.local/share\fP\&. See the \fI\%XDG
Base Directory Specification\fP\&.
.UNINDENT
.UNINDENT
.SH AUTHOR
Microsoft
.SH COPYRIGHT
Copyright (c) Microsoft Corporation. All rights reserved.
.\" Generated by docutils manpage writer.
.