Prerequisites

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

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

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

3. If you plan to use pg_probackup with biha, install the pg-probackup-ent-18 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 cluster init command to initialize the cluster and create the leader node.

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

   bihactl cluster init \
       --biha-node-id=1 \
       --host=host \
       --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 and configure quorum-based synchronous replication.

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

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

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

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 bihactl commands as the same user that starts the Postgres Pro Enterprise server.

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

2. If you plan to use pg_probackup with biha, install the pg-probackup-ent-18 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 cluster init command with the --convert option:

   bihactl init --convert \
       --biha-node-id=1 \
       --host=host \
       --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 and configure quorum-based synchronous replication.

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

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

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 bihactl commands as the same user that starts the Postgres Pro Enterprise server.

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

2. If you plan to use pg_probackup with biha, install the pg-probackup-ent-18 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 cluster init command with the --convert option:

   bihactl init --convert \
       --biha-node-id=1 \
       --host=host \
       --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 and configure quorum-based synchronous replication.

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

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

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

1. When initializing the BiHA cluster from scratch, specify the bihactl cluster init command with the --enable-proxima option. For example:

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

   The bihactl utility adds proxima to the shared_preload_libraries list in the postgresql.conf file, creates the postgresql.proxima.conf file and includes it into the postgresql.biha.conf file.

2. Add followers.

   As followers are added by taking and restoring a backup of the leader, the proxima configuration is copied to the followers, just like other BiHA configuration parameters.

   If you add a referee node, the proxima configuration is not copied to the referee.

Prerequisites

1. If you set up your GDBiHA cluster from scratch, on all nodes of your future cluster, install the postgrespro-ent-18-contrib package. Do not create a database instance.

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

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

3. If you plan to use pg_probackup with biha, install the pg-probackup-ent-18 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 cluster init command to initialize the cluster and create the leader node.

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

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

   If you convert your existing Postgres Pro Enterprise 18 cluster, additionally specify the --convert option.

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

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

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 Segment

In this example, the GDBiHA cluster consists of two segments. The default segment with the 111 identifier is created automatically at the cluster initialization. You must add the second segment manually using the bihactl segment add command.

• Execute the bihactl segment add command with the necessary options:

  bihactl segment add \
      --biha-node-id=segment_id \
      --use-leader "host=node_host port=node_port biha-port=node_biha_port" \
  

Adding Followers

As your GDBiHA cluster consists of six nodes, you must add five followers.

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

2. Execute the bihactl node add command with the necessary options:

   bihactl node add \
       --biha-node-id=2 \
       --host=host \
       --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
       --segment-id=segment_id
   

   If you convert your existing Postgres Pro Enterprise 18 cluster, additionally specify the --convert-standby option.

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

3. Start the DBMS using pg_ctl:

   pg_ctl start -D follower_PGDATA_directory -l follower_log_file
   

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

   SELECT * FROM biha.status_v;
   

5. Repeat the steps above to create all the required followers.

6. When all nodes are ready, check the cluster status in the biha.super_status_v view:

   SELECT * FROM biha.super_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 cluster init, specify the --use-ssl option:

   bihactl init \
       --biha-node-id=1 \
       --host=host \
       --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. Initialize the BiHA cluster using bihactl cluster init:

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

   The bihactl cluster init command output represents the magic string. The magic string example looks as follows:

   dmVyc2lvbj0xIGhvc3Q9bG9jYWxob3N0IHBvcnQ9NTQzMiBiaWhhLXBvcnQ9NTQzMw==
   

2. Copy and save the command output.

3. When adding a follower node using bihactl node add, specify the bihactl cluster init command output as the --magic-string option value. For example:

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

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