PG_AUTOCTL CREATE FORMATION(1)

NAME
pg_autoctl create formation - 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 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. It is possible to show the Postgres URI from the monitor node using the command pg_autoctl show uri <#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 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 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>.

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 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>.

Author
Microsoft

Copyright
Copyright (c) Microsoft Corporation. All rights reserved.