Postgres Pro Standard : Documentation: 18: bihactl : Postgres Professional

bihactl
Prev	Up	Postgres Pro Server Applications	Home	Next

bihactl

bihactl — create a BiHA cluster in Postgres Pro

Synopsis

bihactl cluster init [option...] --biha-listen-addresses --pgdata

bihactl cluster status [option...]

bihactl cluster show-config [option...]

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

bihactl node set front-follower [option...] --id { --magic-file | --magic-string }

bihactl node set leader [option...] --id { --magic-file | --magic-string }

bihactl run [option...]

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

bihactl segment set leader [option...] --id { --magic-file | --magic-string }

bihactl unit set leader [option...] --id { --magic-file | --magic-string }

bihactl upgrade start [option...] { --magic-string | --new-leader-biha-port | --new-leader-host | --new-leader-port | --new-pgdata | --old-bin | --old-pgdata | --subscriber-username }

bihactl upgrade move { --new-magic-string | --new-pgdata | --old-bin | --old-pgdata }

bihactl upgrade finish [option...] { --new-magic-string | --subscriber-username }

bihactl --version

bihactl --help

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, refer to Built-in High Availability (BiHA).

Important

bihactl for Postgres Pro Standard is not supported on Elbrus CPU architecture.

Note

bihactl does not support using the equal sign with include_dir in the postgresql.conf configuration file. For proper operation, use the documented syntax.

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-hosts=hosts]
                     --biha-listen-addresses=addresses
                     [--biha-node-id=node_id]
                     [--biha-port=biha_port]
                     [--cluster-name=cluster_name]
                     [--convert [--server-cert=/path/to/server.crt \
                     --server-key=/path/to/server.key]]
                     [--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
                     [--pg-port=port]
                     [--preferred-roles=preferred_roles_for_replication]
                     [--priority=node_priority]
                     [--replication-hosts=replication_hosts]
                     [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                     --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                     [--sync-standbys=sync_standbys_num [--sync-standbys-min=sync_standbys_min_num]]
                     [--sql-hosts=sql_hosts]
                     [--use-ssl]
                     [--username=name_of_bootstrap_superuser]

Initializes a cluster and sets the leader node. The command must be executed on the server where you want to host the leader. 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.

For more information, refer to Authentication Options, Leader Connection Options, and Network Options.

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

Specifies the unique ID of the node. The value must be integer and greater than zero.

--cluster-name=cluster_name #

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

-C --convert #

Converts the existing node into the leader node of the BiHA cluster. If the name of the bootstrap superuser of your existing node is not postgres, use the --username option to specify this name.

--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. This option is ignored if you convert your existing node using --convert.

Using the --username option of initdb is not supported. Use the --username option of bihactl instead.

-D datadir --pgdata=datadir #

Specifies the directory where the database cluster should be stored. By default, bihactl uses the PGDATA 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 priority that affects both elections and replication in a cluster, in seconds. Possible values: 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. The value must be integer and greater than zero, as well as higher than the value of --sync-standbys-min parameter if set, and must not exceed the number of followers excluding referee. It is recommended to set the sync_standbys_num value less than the value of --minnodes.

-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 confirming transactions. sync_standbys_min_num must be integer and equal to or greater than zero, as well as lower than --sync-standbys. 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 (BCP).

Important

To use SSL for service connections, your installed OpenSSL version must be 1.1.1 or higher. Otherwise, the BiHA cluster is created without SSL for service connections, and a corresponding message is recorded in the log.

--username=name_of_bootstrap_superuser #

Sets the user name of the bootstrap superuser. This defaults to the name of the operating-system user running initdb. Use this option in the following cases:

When you initialize a BiHA cluster from scratch and want to set the bootstrap superuser name other than postgres.
When you convert an existing node where the bootstrap superuser name is not postgres.

Using the --username option of initdb is not supported.

cluster show-config #

Syntax:

bihactl cluster show-config [--biha-listen-addresses=addresses]
                            [--format=data_output_format]
                            [--magic-file=magic_file]
                            [--magic-string=magic_string]
                            [--pg-port=port]
                            [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                            --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]

Displays the full cluster configuration information. An example of a command output in the JSON format looks as follows:

{
  "proxima_enabled": false,
  "use_ssl": false,
  "service_mode": false,
  "user_biha_cert": "",
  "user_biha_key": "",
  "ssl_certificate": "",
  "ssl_private_key": "",
  "ssl_mode": "",
  "synchronous_standby_names": {
   "count": -1,
   "min": -2,
   "names": []
  },
  "unit": {
   "id": 1111,
   "name": "biha_node_1111",
   "can_be_leader": true,
   "can_vote": true,
   "priority": -1,
   "leader_timeout": 20000,
   "mode": "regular",
   "repl_pref_roles": "L",
   "nquorum": 1,
   "minnodes": 1,
   "heartbeat_send_period": 1000,
   "heartbeat_max_lost": 10,
   "no_wal_on_follower": 5000,
   "children": [
    {
     "id": 111,
     "name": "biha_node_111",
     "can_be_leader": true,
     "can_vote": true,
     "priority": -1,
     "leader_timeout": 20000,
     "mode": "regular",
     "repl_pref_roles": "L",
     "nquorum": 2,
     "minnodes": 2,
     "heartbeat_send_period": 1000,
     "heartbeat_max_lost": 10,
     "no_wal_on_follower": 5000,
     "children": [
      {
       "id": 1,
       "name": "biha_node_1",
       "can_be_leader": true,
       "can_vote": true,
       "priority": -1,
       "leader_timeout": 20000,
       "mode": "regular",
       "repl_pref_roles": "L",
       "pg_port": 5432,
       "biha_port": 15432,
       "max_replicas": 2147483647,
       "flw_ro": true,
       "config_send_period": 10000,
       "watchdog_timeout": 2,
       "callbacks_timeout": 10000,
       "asyncaction_timeout": 30000,
       "manage_slots_xmin": true,
       "deny_wal_sources": [],
       "biha_listen_addresses": [
        {
         "address": "biha-db-4",
         "port": -1
        }
       ],
       "sql_hosts": [],
       "replication_hosts": [],
       "biha_hosts": [],
       "unit_type": "node"
      },
      {
       "id": 2,
       "name": "biha_node_2",
       "can_be_leader": true,
       "can_vote": true,
       "priority": -1,
       "leader_timeout": 20000,
       "mode": "regular",
       "repl_pref_roles": "L",
       "pg_port": 5432,
       "biha_port": 5433,
       "max_replicas": 2147483647,
       "flw_ro": true,
       "config_send_period": 10000,
       "watchdog_timeout": 2,
       "callbacks_timeout": 10000,
       "asyncaction_timeout": 30000,
       "manage_slots_xmin": true,
       "deny_wal_sources": [],
       "biha_listen_addresses": [
        {
         "address": "biha-db-2",
         "port": -1
        }
       ],
       "sql_hosts": [],
       "replication_hosts": [],
       "biha_hosts": [],
       "unit_type": "node"
      }
     ],
     "unit_type": "segment"
    }
   ],
   "unit_type": "segment"
  }
 }

For more information, refer to Authentication Options, Leader Connection Options, and Network Options.

--format=data_output_format: Specifies the output format for the configuration information. Possible values are: json (default), yaml.

cluster status #

Syntax:

bihactl cluster status [--biha-listen-addresses=addresses]
                       [--format=data_output_format]
                       [--magic-file=magic_file]
                       [--magic-string=magic_string]
                       [--pg-port=port]
                       [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                       --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]

Checks the node status and displays it in the biha.status_v view.

For more information, refer to Authentication Options, Leader Connection Options, and Network Options.

--format=data_output_format: Specifies the output format for the status information. Possible values are: json, yaml, and table (default).

node add #

Syntax:

bihactl node add [--biha-hosts=hosts]
                 [--biha-listen-addresses=addresses]
                 [--backup-method=backup_method]
                 [--backup-options=backup_options]
                 --biha-node-id=node_id
                 [--biha-port=biha_port]
                 [--can-vote=true_or_false]
                 [--can-be-leader=true_or_false]
                 [--convert-standby [--server-cert=/path/to/server.crt \
                 --server-key=/path/to/server.key]]
                 [--max-replicas=max_number_of_replicas]
                 [--mode=node_mode] [--referee-with-postgres-db]]
                 [--node-name=node_name]
                 --pgdata=datadir
                 [--pg-port=port]
                 [--preferred-roles=preferred_roles_for_replication]
                 [--priority=node_priority]
                 [--replication-hosts=replication_hosts]
                 [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                 --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                 {--segment-id=segment_id | --segment-name=segment_name}
                 {--use-leader=conn_info | --magic-string=magic_string | --magic-file=magic_file}
                 [--sql-hosts=sql_hosts]

Adds a follower node to the initialized cluster. The command must be executed on the server where you want to host a follower. 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, which 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.

For more information, refer to Authentication Options, Leader Connection Options, and Network Options.

-m backup_method --backup-method=backup_method #

Specifies the backup utility. The allowed values are pg_basebackup, pg_probackup, and pg_probackup3. 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 backup options 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. The value must be integer and greater than zero.

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

--can-be-leader #

Determines the ability of a node to become the leader. The default value is true. If set to false, the node 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.

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

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

--preferred-roles=preferred_roles_for_replication #

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

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.

--server-cert=/path/to/server.crt #

Specifies the path to the SSL certificate for the BiHA node in the PEM format.

--server-key=/path/to/server.key #

Specifies the path to the private key for the --server-cert certificate in the PEM format.

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

node set front-follower #

Syntax:

bihactl node set front-follower --id=node_id
                                [--mode=switchover_mode]
                                [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                                --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                                {--magic-string=magic_string | --magic-file=magic_file}

Promotes the node with the specified identifier to the front follower. The promoted node must be located in the follower segment. The command can be executed on any node of a BiHA cluster.

For more information, refer to Authentication Options and Leader Connection Options.

--id=node_id #

Specifies the unique identifier of a node that your want to promote. The node must be located in the follower segment.

--mode=switchover_mode #

Specifies the switchover mode. The following modes are supported:

graceful: The promoted node waits for demotion of the old front follower and, if required, catches up on WAL records. This is the default value.
immediate: The switchover occurs immediately, without waiting. The node with the specified ID changes its state directly to FRONT_FOLLOWER skipping the FOLLOWER_OFFERED state. In this mode, the LEADER_CHANGE_STARTED callback is not called. If the command in the immediate mode is executed on the current front follower, it immediately starts changing its state to FOLLOWER and broadcasts a message about the leader change to other nodes.
Important
The immediate mode is not safe, using it may lead to data loss. It is recommended to enable automatic synchronization by setting the biha.autorewind configuration parameter to true before performing switchover in this mode.

node set leader #

Syntax:

bihactl node set leader --id=node_id
                        [--mode=switchover_mode]
                        [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                        --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                        {--magic-string=magic_string | --magic-file=magic_file}

Promotes the node with the specified identifier to the leader. The promoted node must be located in the leader segment. The command can be executed on any node of a BiHA cluster.

For more information, refer to Authentication Options and Leader Connection Options.

--id=node_id #

Specifies the unique identifier of a node that your want to promote. The node must be located in the leader segment.

--mode=switchover_mode #

Specifies the switchover mode. The following modes are supported:

graceful: The promoted node waits for demotion of the old leader and, if required, catches up on WAL records. This is the default value.
immediate: The switchover occurs immediately, without waiting. The node with the specified ID changes its state directly to LEADER_RW/LEADER_RO skipping the FOLLOWER_OFFERED state. In this mode, the LEADER_CHANGE_STARTED callback is not called. If the command in the immediate mode is executed on the current leader, it immediately starts changing its state to FOLLOWER and broadcasts a message about the leader change to other nodes.
Important
The immediate mode is not safe, using it may lead to data loss. It is recommended to enable automatic synchronization by setting the biha.autorewind configuration parameter to true before performing switchover in this mode.

run #

Syntax:

bihactl run path/to/script.yml
            [--sql-output-format=output_format]

Reads a script located at the specified path and executes commands listed in the script. For more information, refer to Section 26.3.14.

-f output_format --sql-output-format=output_format #: Specifies the script output format. Possible values: json, yaml, table (default), csv.

segment add #

Syntax:

bihactl segment add [--id=segment_id]
                    [--minnodes=min_node_num]
                    [--name=segment_name]
                    [--nquorum=quorum_value]
                    [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                    --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                    {--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. The command can be executed on any node of a BiHA cluster.

For more information, refer to Authentication Options and Leader Connection Options.

-I segment_id --id=segment_id #: Specifies the unique identifier of the segment.
--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.

segment set leader #

Syntax:

bihactl segment set leader --id=segment_id
                           [--mode=switchover_mode]
                           [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                           --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                           {--magic-string=magic_string | --magic-file=magic_file}

Promotes the segment with the specified identifier to the leader segment. The command can be executed on any node of a BiHA cluster.

For more information, refer to Authentication Options and Leader Connection Options.

--id=segment_id #

Specifies the unique identifier of a segment that your want to promote.

--mode=switchover_mode #

Specifies the switchover mode. The following modes are supported:

graceful: The promoted segment waits for demotion of the old leader and, if required, catches up on WAL records. This is the default value.
immediate: The switchover occurs immediately, without waiting. The node with the specified ID changes its state directly to LEADER_RW/LEADER_RO skipping the FOLLOWER_OFFERED state. In this mode, the LEADER_CHANGE_STARTED callback is not called. If the command in the immediate mode is executed on the current leader, it immediately starts changing its state to FOLLOWER and broadcasts a message about the leader change to other nodes.
Important
The immediate mode is not safe, using it may lead to data loss. It is recommended to enable automatic synchronization by setting the biha.autorewind configuration parameter to true before performing switchover in this mode.

unit set leader #

Syntax:

bihactl unit set leader --id=unit_id
                        [--mode=switchover_mode]
                        [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                        --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                        {--magic-string=magic_string | --magic-file=magic_file}

Promotes the specified node or segment depending on the identifier provided. The command can be executed on any node of a BiHA cluster. This command is primarily designed for use in automation scripts.

For more information, refer to Authentication Options and Leader Connection Options.

--id=segment_id #

Specifies the unique identifier of a segment that your want to promote.

--mode=switchover_mode #

Specifies the switchover mode. The following modes are supported:

graceful: The promoted segment waits for demotion of the old leader and, if required, catches up on WAL records. This is the default value.
immediate: The switchover occurs immediately, without waiting. The node with the specified ID changes its state directly to LEADER_RW/LEADER_RO skipping the FOLLOWER_OFFERED state. In this mode, the LEADER_CHANGE_STARTED callback is not called. If the command in the immediate mode is executed on the current leader, it immediately starts changing its state to FOLLOWER and broadcasts a message about the leader change to other nodes.
Important
The immediate mode is not safe, using it may lead to data loss. It is recommended to enable automatic synchronization by setting the biha.autorewind configuration parameter to true before performing switchover in this mode.

upgrade start #

Syntax:

bihactl upgrade start [--convert]
                      [--extra-new-options-gucs -c key=value]
                      [--extra-shared-libs=shared_libraries]
                      {--magic-string=magic_string_of_old_leader | --magic-file=magic_file_of_old_leader}
                      --new-leader-biha-port=new_leader_biha_port
                      --new-leader-host=new_leader_host
                      --new-leader-port=new_leader_port
                      --new-pgdata=new_version_PGDATA_of_leader
                      --old-bin=/path/to/binaries/of/old/version
                      --old-pgdata=old_version_PGDATA
                      [--options=pg_upgrade_options]
                      [--username=superuser_name]
                      [--user-cert=/path/to/client.crt --user-key=/path/to/client.key \
                      [--ssl-mode=ssl_mode]]
                      [--root-cert=/path/to/ca.crt --user-biha-cert=/path/to/client.crt \
                      --user-biha-key=/path/to/client.key [--biha-ssl-mode=ssl_mode]]
                      --subscriber-username=username

Starts major version migration of the BiHA cluster. For more information, refer to Section 26.3.15.1.2.

This command can take the following options:

--convert #

Converts the existing follower into the leader node running the new Postgres Pro Standard version. If you specify this option, specifying --new-leader-biha-port, --new-leader-host, and --new-leader-port is not required.

--extra-new-options-gucs -c key-value #

Specifies a comma-separated list of additional configuration parameters to append to pg_upgrade --new-options.

--extra-shared-libs=shared_libraries #

Specifies shared libraries to be loaded when executing pg_upgrade.

--magic-string=magic_string_of_old_leader #

Uses a magic string that contains encoded data to connect to the leader of the old BiHA cluster, i.e. the cluster that needs to be migrated.

--magic-file=magic_file_of_old_leader #

Specifies the path to a file used to store the magic string with encoded data to connect to the leader of the old BiHA cluster, i.e. the cluster that needs to be migrated.

--new-leader-biha-port=new_leader_biha_port #

Specifies the port of the new leader used to exchange service information between nodes.

--new-leader-host=new_leader_host #

Specifies the new leader host for incoming connections.

--new-leader-port=new_leader_port #

Specifies the new leader port for incoming connections.

--new-pgdata=new_version_PGDATA_of_leader #

Specifies the directory where the new cluster leader running the new Postgres Pro Standard version is created as a result of conversion from the follower of the old version. The directory must be empty.

--old-bin=/path/to/binaries/of/old/version #

Specifies the path to the binaries of the old Postgres Pro Standard version.

--old-pgdata=old_version_PGDATA #

Specifies the directory where the follower running the old Postgres Pro Standard version is created. This follower is then upgraded and converted to the new cluster leader running the new Postgres Pro Standard version. The directory must be empty.

-o pg_upgrade_options --options=pg_upgrade_options #

Specifies additional options of pg_upgrade.

--ssl-mode=ssl_mode #

Determines the SSL authentication policy for --subscriber-username. The following modes are supported:

verify-full (default)
require
verify-ca

For more information about modes, see sslmode.

--subscriber-username=username #

Specifies the username for the pg_createsubscriber connection. This user must have privileges for creating subscriptions and using pg_replication_origin_advance().

--username=name_of_bootstrap_superuser #

Sets the user name of the bootstrap superuser. This defaults to the name of the operating-system user running initdb. Use this option in the following cases:

When you initialize a BiHA cluster from scratch and want to set the bootstrap superuser name other than postgres.
When you convert an existing node where the bootstrap superuser name is not postgres.

Using the --username option of initdb is not supported.

--user-cert=/path/to/client.crt #

Specifies the path to the SSL certificate for --subscriber-username authentication in the PEM format.

--user-key=/path/to/client.key #

Specifies the path to the private key for the --user-cert certificate in the PEM format.

upgrade move #

Syntax:

bihactl upgrade move --new-magic-string=magic_string_of_new_leader
                     --new-pgdata=new_version_PGDATA_of_follower
                     --old-bin=/path/to/binaries/of/old/version
                     --old-pgdata=old_version_PGDATA_of_follower

Moves a follower from the old BiHA cluster to the new BiHA cluster during major version migration. For more information, refer to Section 26.3.15.1.2.

This command can take the following options:

--new-magic-string=magic_string_of_new_leader #: Uses a magic string that contains encoded data to connect to the leader of the new BiHA cluster, i.e. the cluster upgraded to the new major version. The magic string is provided as the result of the bihactl upgrade start command.
--new-pgdata=new_version_PGDATA_of_follower #: Specifies the directory where the follower running the new Postgres Pro Standard version is moved. The directory must be empty.
--old-bin=/path/to/binaries/of/old/version #: Specifies the path to the binaries of the old Postgres Pro Standard version.
--old-pgdata=old_version_PGDATA #: Specifies the directory where the follower running the old Postgres Pro Standard version currently locates.

upgrade finish #

Syntax:

bihactl upgrade finish --new-magic-string=magic_string_of_new_leader
                       [--username=superuser_name]
                       [--user-cert=/path/to/client.crt --user-key=/path/to/client.key \
                       [--ssl-mode=ssl_mode]]
                       --subscriber-username=username

Finishes major version migration of a BiHA cluster. For more information, refer to Section 26.3.15.1.2.

This command can take the following options:

--new-magic-string=magic_string_of_new_leader #

Uses a magic string that contains encoded data to connect to the leader of the new BiHA cluster, i.e. the cluster upgraded to the new major version. The magic string is provided as the result of the bihactl upgrade start command.

--ssl-mode=ssl_mode #

Determines the SSL authentication policy for --subscriber-username. The following modes are supported:

verify-full (default)
require
verify-ca

For more information about modes, see sslmode.

--subscriber-username=username #

Specifies the username for the pg_createsubscriber connection. This user must have privileges for creating subscriptions and using pg_replication_origin_advance().

--username=name_of_bootstrap_superuser #

Sets the user name of the bootstrap superuser. This defaults to the name of the operating-system user running initdb. Use this option in the following cases:

When you initialize a BiHA cluster from scratch and want to set the bootstrap superuser name other than postgres.
When you convert an existing node where the bootstrap superuser name is not postgres.

Using the --username option of initdb is not supported.

--user-cert=/path/to/client.crt #

Specifies the path to the SSL certificate for --subscriber-username authentication in the PEM format.

--user-key=/path/to/client.key #

Specifies the path to the private key for the --user-cert certificate in the PEM format.

-v | --version #

Syntax:

bihactl -v
bihactl --version

Displays the current version of the bihactl utility.

--help #

Syntax:

bihactl --help

Displays command-line help.

Authentication Options #

You can use these options with the following commands: bihactl cluster init, bihactl cluster show-config, bihactl cluster status, bihactl node add, bihactl node set front-follower, bihactl node set leader, bihactl segment add, bihactl segment set leader, and bihactl unit set leader.

--biha-ssl-mode=ssl_mode #

Determines the SSL authentication policy for the biha_replication_user role. The following modes are supported:

verify-full (default)
require
verify-ca

For more information about modes, see sslmode.

--root-cert=/path/to/ca.crt #

Specifies the path to the trusted CA certificate in the PEM format.

--server-cert=/path/to/server.crt #

Specifies the path to the SSL certificate for the BiHA node in the PEM format.

--server-key=/path/to/server.key #

Specifies the path to the private key for the --server-cert certificate in the PEM format.

--user-biha-cert=/path/to/client.crt #

Specifies the path to the SSL certificate for the biha_replication_user role authentication in the PEM format.

--user-biha-key=/path/to/client.key #

Specifies the path to the private key for the --user-biha-cert certificate in the PEM format.

Leader Connection Options #

The --use-leader option is used with bihactl node add and bihactl segment add commands.

The --magic-file and --magic-string options are used with bihactl cluster show-config, bihactl cluster status, bihactl node add, bihactl node set front-follower, bihactl node set leader, bihactl segment add, bihactl segment set leader, and bihactl unit set leader.

-f magic_file --magic-file=magic_file #

Specifies the path to a file used to store the magic string with encoded data to connect to the leader node. When this parameter is used with bihactl cluster init command, the generated magic string is saved in the file specified. When used with other commands, the magic string from the file is used to connect to the leader. The file must exist when you execute the commands.

-s magic_string --magic-string=magic_string #

Specifies the magic string that contains encoded data to connect to the leader node. The magic string is generated in the output of the bihactl cluster init command and looks as follows:

dmVyc2lvbj0xIGhvc3Q9bG9jYWxob3N0IHBvcnQ9NTQzMiBiaWhhLXBvcnQ9NTQzMw==

-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

Network Options #

The --biha-listen-addresses and --biha-port options are used with bihactl cluster init, bihactl node add, bihactl cluster show-config, and bihactl cluster status.

The --biha-hosts, --sql-hosts, --replication-hosts, and --pg-port options are used with bihactl cluster init and bihactl node add commands.

--biha-hosts=hosts #

Used by other nodes to connect to the current node by internal control channel (BCP), for example, using a proxy server or a tunnel. If the biha_hosts value is empty, by default, the --biha-listen-addresses value of the current node is used.

Possible values: one or several comma-separated addresses in the hostname:port format. port is an optional value, if not specified or set to -1, the --biha-port value of the current node is used.

For example: biha-db-1:5433,biha-proxy:8081

-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 --pg-port + 1.

--biha-listen-addresses=addresses #

Determines on which addresses listening sockets are open for the internal BCP control channel.

For example: biha-db-1:5433,biha-proxy:8081

-p port --pg-port=port #

Specifies the node port for incoming connections to Postgres Pro.

If not specified, bihactl uses the default 5432 value.

--replication-hosts=replication_hosts #

Used by other nodes to connect to the current node by replication channel. The --biha-listen-addresses value must include replication_hosts. If the replication_hosts value is empty, by default, the --biha-listen-addresses value of the current node is used.

The maximum string size is 1024 bytes, otherwise it is ignored.

For example: biha-db-1:5433,biha-proxy:8081

--sql-hosts=sql_hosts #

Used by other nodes to execute SQL queries to the current node. If the sql_hosts value is empty, by default, the --replication-hosts value of the current node is used.

The maximum string size is 1024 bytes, otherwise it is ignored.

For example: biha-db-1:5433,biha-proxy:8081

bihactl

Synopsis

Description

Important

Note

Command-Line Reference #

cluster init #

Important

Important

cluster show-config #

cluster status #

node add #

Note

Important

node set front-follower #

Important

node set leader #

Important

run #

segment add #

segment set leader #

Important

unit set leader #

Important

upgrade start #

upgrade move #

upgrade finish #

-v | --version #

--help #

Authentication Options #

Leader Connection Options #

Network Options #

See Also