Request a Demo
bihactl
Prev UpPostgres Pro Server ApplicationsHome Next

bihactl

bihactl — create a BiHA cluster in Postgres Pro

Synopsis

bihactl cluster init [option...] --host --pgdata

bihactl cluster status [option...]

bihactl cluster show-config [option...]

bihactl node add [option...] --pgdata { --use-leader | --magic-file | --magic-string }

bihactl segment add [option...] { --use-leader | --magic-file | --magic-string }

Description

bihactl is a command line utility that allows creating a BiHA cluster, changing its composition, as well as monitoring the cluster status. For more information about the BiHA solution, see Built-in High Availability (BiHA).

Important

bihactl for Postgres Pro Enterprise 18 maintains backward compatibility with bihactl for Postgres Pro Enterprise 16.X and 17.X. However, bihactl commands for previous versions are considered deprecated, therefore it is recommended to use bihactl commands provided in this document.

This section contains information about the bihactl utility commands:

The follower node can be added using a magic string saved after the bihactl cluster init command by adding the -s option to the bihactl bihactl node add command.

Command-Line Reference #

cluster init #

Syntax: 

bihactl cluster init [--biha-node-id=node_id]
                     [--biha-port=biha_port]
                     [--cluster-name=cluster_name]
                     [--convert]
                     [--enable-proxima]
                     --host=host
                     [--magic-file=magic_file]
                     [--max-replicas=max_number_of_replicas]
                     [--minnodes=min_node_num]
                     [--node-name=node_name]
                     [--no-password]
                     [--nquorum=quorum_value]
                     [--options=initdb_options]
                     --pgdata=datadir
                     [--port=port]
                     [--preferred-roles=preferred_roles_for_replication]
                     [--priority=node_priority]
                     [--sync-standbys=sync_standbys_num [--sync-standbys-min=sync_standbys_min_num]]
                     [--use-ssl]

Initializes a cluster and sets the leader node. When this command is executed, bihactl accesses the initdb utility, and at this stage you can also specify its parameters with the -o option or using initdb options directly.

This command can take the following options:

-I node_id
--biha-node-id=node_id #

Specifies the unique ID of the node.

-P biha_port
--biha-port=biha_port #

Specifies the port used to exchange service information between nodes. If not specified, the value is set to --port + 1.

--cluster-name=cluster_name #

Specifies the name of the BiHA cluster. The default name is biha_node_1111.

-C
--convert #

Converts an existing node to make it the leader node in the high-availability cluster.

-x
--enable-proxima #

Enables the proxima extension with the default parameters in a BiHA cluster when you create it from scratch or on the leader node when you convert the existing primary-standby cluster into a BiHA cluster.

-h host
--host=host #

Specifies the host for incoming connections. The default value is PGHOST.

-f magic_file
--magic-file=magic_file #

Specifies the path to the magic file that contains encoded data to connect to the leader node. The file must exist when you execute the bihactl node add command.

--max-replicas=max_number_of_replicas #

Specifies the maximum number of biha replication connections to a node, i.e. the maximum number of walsenders where application_name is biha_node_*.

Possible values are: 0, INT_MAX. The default value is INT_MAX, the number of connections is unlimited.

-M min_node_num
--minnodes=min_node_num #

Specifies the minimum number of operational nodes for the leader node to be open for write transactions. If not specified, the value equals the --nquorum value.

--no-password #

If set, bihactl does not prompt you to manually specify the password for the biha_replication_user role.

--node-name=node_name #

Specifies the leader node name.

-N quorum_value
--nquorum=quorum_value #

Specifies the minimum number of nodes which must vote for the new leader node if the current leader is down. The default value is 2.

When setting up this value, consider the split-brain risk. It is recommended to use the following formula: (total_number_of_nodes + 1)/2. For example, if your cluster has 3 nodes, the quorum_value value must be 2.

-o initdb_options
--options=initdb_options #

Specifies additional options of initdb.

-D datadir
--pgdata=datadir #

Specifies the directory where the database cluster should be stored. By default, bihactl uses the PGDATA value.

-p port
--port=port #

Specifies the node port for incoming connections.

If not specified, bihactl uses the default 5432 value.

--preferred-roles=preferred_roles_for_replication #

Specifies the preferred role of a node for replication in a BiHA cluster with cascading replication.

Possible values are: combinations of L (leader), F (follower), and R (referee). The value must be 1 to 3 symbols long and must not contain repeatable symbols. For example: L, F, LFR, or LF.

The default value is L, meaning that data is replicated from the leader only.

--priority=node_priority #

Sets the node weight that affects both elections and replication in a cluster, in milliseconds. Possible values are: 0, INT_MAX. The default value is -1, meaning that the parameter is ignored. You can modify this parameter value only by the biha.set_priority function.

BiHA uses this configuration parameter for the following purposes:

  • To set the replication start timeout when selecting the replication source in a BiHA cluster with configured cascading replication. The higher the value, the later the node starts replication and allows connection of nodes with lower priority. The parameter is required for the nodes to establish the cascading replication schema automatically.

  • To set the node priority in a cluster with synchronous replication. The value determines the timeout that must be reached before the node stands as a candidate in elections. The zero value indicates the highest priority.

    Important

    To ensure correct operation of this parameter, set the --sync-standbys value one unit less than the total number of cluster nodes.

-Y sync_standbys_num
--sync-standbys=sync_standbys_num #

Enables quorum-based synchronous replication by setting the synchronous_standby_names parameter and specifying the number of synchronous standbys (quorum) with the ANY method. It is recommended that the sync_standbys_num value be less than the value of the --minnodes option.

-y sync_standbys_min_num
--sync-standbys-min=sync_standbys_min_num #

Enables relaxed quorum-based synchronous replication by specifying the MIN field value of the synchronous_standby_names parameter, which is the minimum number of synchronous standbys that must be available for the leader node to continue operation. The sync_standbys_min_num value must be lower than --sync-standbys, but cannot be negative. If the option is not specified, the BiHA cluster operates according to the default synchronous replication restrictions, i.e. the leader node is not available for write transactions until all followers catch up with its current state.

-S
--use-ssl #

Enables the protected mode of the service information exchange between cluster nodes with SSL/TLS over the biha control channel.

cluster show-config #

Syntax: 

bihactl cluster show-config [--format=data_output_format]
                            [--host=host]
                            [--magic-file=magic_file]
                            [--magic-string=magic_string]
                            [--port=port]

Displays the full cluster configuration information. This command can take the following options:

--format=data_output_format

Specifies the output format for the status information. Possible values are: json, yaml, and table.

-h host
--host=host

Specifies the host for incoming connections. The default value is PGHOST.

-f magic_file
--magic-file=magic_file

Specifies the path to the magic file that contains encoded data to connect to the leader node.

-s magic_string
--magic-string=magic_string

Specifies the magic string that contains encoded data to connect to the leader node.

-p port
--port=port

Specifies the node port for incoming connections.

If not specified, bihactl uses the default 5432 value.

cluster status #

Syntax: 

bihactl cluster status [--format=data_output_format]
                       [--host=host]
                       [--magic-file=magic_file]
                       [--magic-string=magic_string]
                       [--port=port]

Checks the node status and displays it in the biha.status_v view. This command can take the following options:

--format=data_output_format

Specifies the output format for the status information. Possible values are: json, yaml, and table.

-h host
--host=host

Specifies the host for incoming connections. The default value is PGHOST.

-f magic_file
--magic-file=magic_file

Specifies the path to the magic file that contains encoded data to connect to the leader node.

-s magic_string
--magic-string=magic_string

Specifies the magic string that contains encoded data to connect to the leader node.

-p port
--port=port

Specifies the node port for incoming connections.

If not specified, bihactl uses the default 5432 value.

node add #

Syntax: 

bihactl node add [--backup-method=backup_method]
                 [--backup-options=backup_options]
                 [--biha-node-id=node_id]
                 [--biha-port=biha_port]
                 [--can-vote=true_or_false]
                 [--convert-standby]
                 [--host=host]
                 [--max-replicas=max_number_of_replicas]
                 [--mode=node_mode] [--referee-with-postgres-db]]
                 [--name=node_name]
                 [--pgdata=datadir]
                 [--port=port]
                 [--preferred-roles=preferred_roles_for_replication]
                 [--priority=node_priority]
                 {--segment-id=segment_id | --segment-namesegment_name}
                 {--use-leader=conn_info | --magic-string=magic_string | --magic-file=magic_file}

Adds a follower node to the initialized cluster. When this command is executed, a backup of the leader node is created by means of pg_basebackup or pg_probackup. When you add a node, bihactl keeps the replication slot by calling pg_basebackup with the --slot=SLOT_NAME, --wal-method=stream, --checkpoint=fast parameters or pg_probackup with the --stream --slot=SLOT_NAME parameters that prevents deletion of WAL on the leader during backup.

Note

You must add nodes one by one. Do not add a new node if creation of a previously added node has not been completed yet and the node is in the CSTATE_FORMING state. Otherwise, you may encounter the following error: 

          WARNING:  aborting backup due to backend exiting before pg_backup_stop was
          called

The backup utility can be set with the -m option, while the parameters of the selected backup are specified with the -O option.

This command can take the following options:

-m backup_method
--backup-method=backup_method #

Specifies the backup utility. The allowed values are pg_basebackup and pg_probackup. The default value is pg_basebackup. If you do not specify the --backup-method option, the default backup method is used. The pg_basebackup utility is the only value that can be used when adding the referee node.

-O backup_options
--backup-options=backup_options #

Specifies additional options of pg_basebackup or pg_probackup depending on the backup utility specified in the --backup-method option.

-I node_id
--biha-node-id=node_id #

Specifies the unique ID of the node.

-p port
--port=port #

Specifies the node port for incoming connections.

If not specified, bihactl uses the default 5432 value.

--can-vote #

Determines whether a node is allowed to vote. The default value is true. If set to false, the node cannot vote, as well as cannot stand as a candidate in elections of the new leader.

-c
--convert-standby #

Converts an existing node to make it a follower node in the high-availability cluster. The node should be a leader node replica prior to the conversion.

-h host
--host=host #

Specifies the host for incoming connections. The default value is PGHOST.

-f magic_file
--magic-file=magic_file #

Uses a magic file that contains encoded data to connect to the leader node.

-s magic_string
--magic-string=magic_string #

Uses a magic string that contains encoded data to connect to the leader node.

--max-replicas=max_number_of_replicas #

Specifies the maximum number of biha replication connections to a node, i.e. the maximum number of walsenders where application_name is biha_node_*.

Possible values are: 0, INT_MAX. The default value is INT_MAX, the number of connections is unlimited.

-r node_mode
--mode=node_mode #

Specifies the operation mode of the node. The allowed values are as follows:

  • regular — the node can operate as the leader or as a follower. This is the default value.

  • referee — the node only participates in the leader elections and does not contain any user databases.

  • referee_with_wal — the node participates both in the leader elections in the same way as in the referee mode and receives the entire WAL from the leader node.

By default, the postgres database is not copied to a node in referee or referee_with_wal modes. To copy the postgres database to the referee, use the --referee-with-postgres-db option.

--name=node_name #

Specifies the follower node name. If not specified, the name is generated automatically as biha_node_ + --biha-node-id. For example, if --biha-node-id is 1, the name is biha_node_1.

-D datadir
--pgdata=datadir #

Specifies the directory where the database cluster should be stored. If not specified, bihactl uses the PGDATA value.

-P biha_port
--biha-port=biha_port #

Specifies the port used to exchange service information between nodes. If not specified, the value is set to --port + 1.

--preferred-roles=preferred_roles_for_replication #

Specifies the preferred role of a node for replication in a BiHA cluster with cascading replication.

Possible values are: combinations of L (leader), F (follower), and R (referee). The value must be 1 to 3 symbols long and must not contain repeatable symbols. For example: L, F, LFR, or LF.

The default value is L, meaning that data is replicated from the leader only.

--priority=node_priority #

Sets the node weight that affects both elections and replication in a cluster, in milliseconds. Possible values are: 0, INT_MAX. The default value is -1, meaning that the parameter is ignored. You can modify this parameter value only by the biha.set_priority function.

BiHA uses this configuration parameter for the following purposes:

  • To set the replication start timeout when selecting the replication source in a BiHA cluster with configured cascading replication. The higher the value, the later the node starts replication and allows connection of nodes with lower priority. The parameter is required for the nodes to establish the cascading replication schema automatically.

  • To set the node priority in a cluster with synchronous replication. The value determines the timeout that must be reached before the node stands as a candidate in elections. The zero value indicates the highest priority.

    Important

    To ensure correct operation of this parameter, set the --sync-standbys value one unit less than the total number of cluster nodes.

-R
--referee-with-postgres-db #

Copies the postgres database with all the objects to the referee node. You can only use this option when adding a node in the referee or referee_with_wal mode.

--segment-id=segment_id #

Specifies the unique identifier of the segment where the node is added to. If you do not specify the segment, the node is added to the default 111 segment. You must use either --segment-id or --segment-name to specify the segment.

--segment-name=segment_name #

Specifies the name of the segment where the node is added to. If you do not specify the segment, the node is added to the default 111 segment. You must use either --segment-name or --segment-id to specify the segment.

-l conn_info
--use-leader=conn_info #

Specifies parameters to connect to the leader node in the following format: 

host=leader_host port=leader_port biha-port=leader_biha_port

segment add #

Syntax: 

bihactl segment add [--id=segment_id]
                    [--minnodes=min_node_num]
                    [--name=segment_name]
                    [--nquorum=quorum_value]
                    {--use-leader=conn_info | --magic-string=magic_string | --magic-file=magic_file}

Adds a segment that is used to unite several BiHA cluster nodes located in one data center.

Warning

This command is a part of the geographical distribution and disaster resilience functionality, which is currently experimental and is not recommended for using in production.

This command can take the following options:

-I segment_id
--id=segment_id #

Specifies the unique identifier of the segment.

-f magic_file
--magic-file=magic_file #

Uses a magic file that contains encoded data to connect to the cluster node.

-s magic_string
--magic-string=magic_string #

Uses a magic string that contains encoded data to connect to the cluster node.

--name=segment_name #

Specifies the segment name. If not specified, the name is generated automatically as biha_node_ + --id. For example, if --id is 1, the name is biha_node_1.

-l conn_info
--use-leader=conn_info #

Specifies parameters to connect to the cluster node in the following format: 

host=node_host port=node_port biha-port=node_biha_port

Prev Up Next
Postgres Pro Server Applications Home initdb
epub pdf