Prerequisites

1. On all nodes of your future cluster, install the postgrespro-ent-16-contrib package. Do not create a database instance.

2. Ensure that you execute the bihactl command as the same user that starts the Postgres Pro Enterprise server.

   For example, if you start the server as user postgres, the bihactl command must also be run by user postgres.

3. If you plan to use pg_probackup with biha, install the pg-probackup-ent-16 package.

4. Choose the authentication method for the biha_replication_user role and make required preparations. For more information, see User Authentication Configuration.

Initializing the cluster

Use the bihactl init command to initialize the cluster and create the leader node.

1. Execute the bihactl init command with the necessary options:

   bihactl init \
       --biha-node-id=1 \
       --host=node_1 \
       --port=node_port_number \
       --biha-port=biha_port_number \
       --nquorum=number_of_nodes \
       --pgdata=leader_PGDATA_directory
   

   At this stage, you can also enable SSL for cluster service connections, configure quorum-based synchronous replication, and configure SSL authentication for the biha_replication_user role.

2. (Optional) Specify the password for the biha_replication_user role and re-enter the password for verification.

   Note

   bihactl prompts you to specify the password for the biha_replication_user role only if you have not configured any supported authentication methods. If so, the leader is created, however, adding followers is not available. To create a full-featured BiHA cluster, configure user authentication.

   The initdb utility is accessed, postgresql.conf and pg_hba.conf files are modified.

   When initializing the BiHA cluster, the magic string is generated. For more information on how to use the magic string, see Section 27.2.8.

3. Start the DBMS using pg_ctl:

   pg_ctl start -D leader_PGDATA_directory -l leader_log_file
   

4. Check the node status in the biha.status_v view:

   SELECT * FROM biha.status_v;
   

Adding a follower node

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

1. Ensure that the leader node is in the LEADER_RO or LEADER_RW state.

2. Ensure that you configure the biha_replication_user role authentication using one of the supported methods.

3. Execute the bihactl add command with the necessary options:

   bihactl add \
       --biha-node-id=2 \
       --host=node_2 \
       --port=node_port_number \
       --biha-port=biha_port_number \
       --use-leader "host=leader_host port=leader_port biha-port=leader_biha_port" \
       --pgdata=follower_PGDATA_directory
   

   A backup of the leader node is created by means of pg_basebackup or pg_probackup depending on the value set in the --backup-method option. Besides, postgresql.conf and pg_hba.conf files are modified.

   Note

   During this process, all files are copied from the leader to the new node. The larger the database size, the longer it takes to add the follower.

   You can also add the leader node connection data using the magic string. For more information on how to use the magic string, see Section 27.2.8.

4. Start the DBMS using pg_ctl:

   pg_ctl start -D follower_PGDATA_directory -l follower_log_file
   

5. Check the node status in the biha.status_v view:

   SELECT * FROM biha.status_v;
   

Prerequisites

1. Ensure that you execute the bihactl command as the same user that starts the Postgres Pro Enterprise server.

   For example, if you start the server as user postgres, the bihactl command must also be run by user postgres.

2. If you plan to use pg_probackup with biha, install the pg-probackup-ent-16 package.

3. Choose the authentication method for the biha_replication_user role and make required preparations. For more information, see User Authentication Configuration.

Converting the existing primary node into the leader node

1. Stop the existing primary node using pg_ctl:

   pg_ctl stop -D primary_PGDATA_directory
   

2. Execute the bihactl init command with the --convert option:

   bihactl init --convert \
       --biha-node-id=1 \
       --host=node_1 \
       --port=PostgresPro_port \
       --biha-port=biha_port_number \
       --nquorum=number_of_nodes \
       --pgdata=leader_PGDATA_directory
   

   At this stage, you can also enable SSL for cluster service connections, configure quorum-based synchronous replication, and configure SSL authentication for the biha_replication_user role.

   When converting the cluster, the magic string is generated. For more information on how to use the magic string, see Section 27.2.8.

3. (Optional) Specify the password for the biha_replication_user role and re-enter the password for verification.

   Note

   bihactl prompts you to specify the password for the biha_replication_user role only if you have not configured any supported authentication methods. If so, the leader is created, however, adding followers is not available. To create a full-featured BiHA cluster, configure user authentication.

4. Start the DBMS using pg_ctl:

   pg_ctl start -D leader_PGDATA_directory -l leader_log_file
   

5. Check the node status in the biha.status_v view:

   SELECT * FROM biha.status_v;
   

Converting the existing standby node into the follower node

1. Ensure that you configure the biha_replication_user role authentication using one of the supported methods.

2. Stop the existing standby node using pg_ctl:

   pg_ctl stop -D standby_PGDATA_directory
   

3. Execute the bihactl add command with the --convert-standby option:

   bihactl add --convert-standby \
     --biha-node-id=2 \
     --host=node_2 \
     --port=PostgresPro_port \
     --biha-port=5435 \
     --use-leader "host=leader_host port=leader_port biha-port=leader_biha_port" \
     --pgdata=follower_PGDATA_directory
   

   When converting an existing standby node into the follower node, biha creates the follower_PGDATA_directory/pg_biha/biha.conf and follower_PGDATA_directory/pg_biha/biha.state files required for the node to be connected to the cluster and modifies postgresql.conf and pg_hba.conf.

   You can also add the leader node connection data using the magic string. For more information on how to use the magic string, see Section 27.2.8.

4. Start the DBMS using pg_ctl:

   pg_ctl start -D follower_PGDATA_directory -l follower_log_file
   

5. Check the node status in the biha.status_v view:

   SELECT * FROM biha.status_v;
   

Prerequisites

1. Ensure that you execute the bihactl command as the same user that starts the Postgres Pro Enterprise server.

   For example, if you start the server as user postgres, the bihactl command must also be run by user postgres.

2. If you plan to use pg_probackup with biha, install the pg-probackup-ent-16 package.

3. Choose the authentication method for the biha_replication_user role and make required preparations. For more information, see User Authentication Configuration.

Converting the existing node into the leader node

1. Stop the existing node using pg_ctl:

   pg_ctl stop -D server_PGDATA_directory
   

2. Execute the bihactl init command with the --convert option:

   bihactl init --convert \
       --biha-node-id=1 \
       --host=node_1 \
       --port=PostgresPro_port \
       --biha-port=biha_port_number \
       --nquorum=number_of_nodes \
       --pgdata=leader_PGDATA_directory
   

   At this stage, you can also enable SSL for cluster service connections, configure quorum-based synchronous replication, and configure SSL authentication for the biha_replication_user role.

   The postgresql.conf and pg_hba.conf files are modified.

   When converting the node, the magic string is generated. For more information on how to use the magic string, see Section 27.2.8.

3. (Optional) Specify the password for the biha_replication_user role and re-enter the password for verification.

   Note

   bihactl prompts you to specify the password for the biha_replication_user role only if you have not configured any supported authentication methods. If so, the leader is created, however, adding followers is not available. To create a full-featured BiHA cluster, configure user authentication.

4. Start the DBMS using pg_ctl:

   pg_ctl start -D leader_PGDATA_directory -l leader_log_file
   

5. Check the node status in the biha.status_v view:

   SELECT * FROM biha.status_v;
   

Adding the follower node

1. Ensure that the leader node is in the LEADER_RO or LEADER_RW state.

2. Ensure that you configure the biha_replication_user role authentication using one of the supported methods.

3. Execute the bihactl add command with the necessary options:

    bihactl add \
        --biha-node-id=2 \
        --host=node_2 \
        --port=node_port_number \
        --biha-port=biha_port_number \
        --use-leader "host=leader_host port=leader_port biha-port=leader_biha_port" \
        --pgdata=follower_PGDATA_directory
    

   A backup of the leader node is created by means of pg_basebackup or pg_probackup depending on the value set in the --backup-method option. Besides, postgresql.conf and pg_hba.conf files are modified.

   You can also add the leader node connection data using the magic string. For more information on how to use the magic string, see Section 27.2.8.

4. Start the DBMS using pg_ctl:

   pg_ctl start -D follower_PGDATA_directory -l follower_log_file
   

5. Check the node status in the biha.status_v view:

   SELECT * FROM biha.status_v;
   

1. Execute the bihactl add command with the relevant value of the --mode option:

   bihactl add \
       --biha-node-id=3 \
       --host=node_3 \
       --port=node_port_number \
       --biha-port=biha_port_number \
       --use-leader "host=leader_host port=leader_port biha-port=leader_biha_port" \
       --pgdata=referee_PGDATA_directory \
       --mode=referee
   

   or

   bihactl add \
       --biha-node-id=3 \
       --host=node_3 \
       --port=node_port_number \
       --biha-port=biha_port_number \
       --use-leader "host=leader_host port=leader_port biha-port=leader_biha_port" \
       --pgdata=referee_PGDATA_directory \
       --mode=referee_with_wal
   

2. Check the shared_buffers configuration parameter of the referee.

   If it is too high, set the value to the default 128 MB.

3. Using pg_ctl, start the Postgres Pro instance where you have set up the referee:

   pg_ctl start -D referee_PGDATA_directory
   

4. Check the node status in the biha.status_v view:

   SELECT * FROM biha.status_v;
   

Preparing a Certificate and Key Pair

• Using the OpenSSL utility, generate a certificate and a private key and save them in the /PGDATA/pg_biha directory on each cluster node:

  openssl req -x509 -newkey rsa:4096 -keyout path_to_key -out path_to_certificate -sha256 -days period_of_validity -nodes -subj "/CN=certificate_domain"
  

  For example:

  openssl req -x509 -newkey rsa:4096 -keyout /PGDATA/pg_biha/biha_priv_key.pem -out /PGDATA/pg_biha/biha_pub_cert.pem -sha256 -days 365 -nodes -subj "/CN=localhost"
  

  The following files are generated:

  • biha_priv_key.pem is a private key with read and write user access (0600)

  • biha_pub_cert.pem is a self-signed certificate issued for the specified time period and domain

  Important

  Ensure that you use the above mentioned names for your certificate and private key files as BiHA searches for the files by these names.

Enabling SSL

1. When you initialize a BiHA cluster with bihactl init, specify the --use-ssl option:

   bihactl init \
       --biha-node-id=1 \
       --host=node_1 \
       --port=node_port_number \
       --biha-port=biha_port_number \
       --nquorum=number_of_nodes \
       --pgdata=leader_PGDATA_directory
       --use-ssl
   

2. To ensure that SSL is enabled, when your BiHA cluster is set up, check that the biha.use_ssl parameter is set to true using the SHOW command:

   SHOW biha.use_ssl;
   

1. When initializing the cluster, redirect the bihactl output to a file:

   bihactl init \
      --biha-node-id=1 \
      --host=node_1 \
      --port=node_port_number \
      --biha-port=biha_port_number \
      --nquorum=number_of_nodes \
      --pgdata=leader_PGDATA_directory > /tmp/magic-file
   

2. When adding a follower node, do the following:

   1. Set up an environment variable:

      export MAGIC_STRING="$(cat /tmp/magic-file)"
      

   2. Add --magic-string as a bihactl add option:

      bihactl add \
       --biha-node-id=2 \
       --host=node_2 \
       --port=node_port_number \
       --biha-port=biha_port_number \
       --magic-string=$MAGIC_STRING \
       --pgdata=follower_PGDATA_directory
      

   The follower node will now use the encoded data from the magic string to connect to the leader node.