The BiHA cluster is set up by means of the bihactl utility. There are several scenarios of using the bihactl utility:
Before you start setting up the BiHA cluster, carefully read Prerequisites and Considerations.
Before you begin to set up the BiHA cluster, read the following information and perform the required actions if needed:
The BiHA solution for Postgres Pro Enterprise is not supported on Elbrus CPU architecture.
Ensure network connectivity between all nodes of your future BiHA cluster.
If network isolation is required, when both the control channel and WAL transmission operate in one network, while client sessions with the database operate in another network, configure the BiHA cluster as follows:
Use host names resolving to IP addresses of the network for the control channel and WAL.
Add the IP address for client connections to
the listen_addresses configuration parameter.
Ensure time synchronization on all cluster nodes. Time synchronization in the cluster is critical for data consistency, event sequencing, and operation of the distributed system. Lack of synchronization may have a negative impact on BiHA operation.
If you want to use SSL for service connections, ensure that your installed OpenSSL version is 1.1.1 or higher.
BiHA creates a number of auxiliary files and configures some Postgres Pro configuration parameters to ensure proper operation. For more information, see Postgres Pro Configuration.
It is not recommended to execute the bihactl commands
in the PGDATA directory. The bihactl
utility may create the biha_init.log and biha_add.log
files in the directory where it is executed. However, the target PGDATA
directory must be empty for proper execution of bihactl commands,
except the case when you set up your BiHA cluster
from the existing cluster with streaming replication.
You can configure user authentication using the password file, the environment variable, or SSL. For more information, see User Authentication Configuration.
During operation, BiHA uses its own mechanism to modify the Postgres Pro configuration dynamically. Some Postgres Pro parameters are managed by biha and cannot be modified using ALTER SYSTEM, as they are essential for biha operation. These parameters are the following:
For more information, see Postgres Pro Configuration.
When using BiHA, it is not recommended to manually
modify any configuration parameters related to WAL application as this
may cause unexpected cluster behavior. For example, modifying the
recovery_min_apply_delay value on a follower
may interrupt its WAL receipt, even though the follower will be displayed
as online and in the FOLLOWER state.
It is not recommended to use restore_command with
the BiHA cluster. For more information about recovery
from a backup, see Section 27.3.14.
In some operating systems, user session management may be handled by systemd. In this case, if your server is started using pg_ctl and managed remotely, be aware that all background processes initiated within an SSH session will be terminated by the systemd daemon when the session ends. To avoid such behavior, you can do one of the following:
Use the postgrespro-ent-17
systemd unit file to start the DBMS server
on the cluster node.
Modify the configuration of the user session management service called
systemd-logind in the
/etc/systemd/logind.conf file, specifically, set
the KillUserProcesses parameter to
no.
Ensure that the hot_standby_feedback configuration
parameter is not specified or is set to off. Otherwise,
setting the new leader can lead to holding the horizon by one or more
replication slots.
The biha_replication_user
role is created during cluster initialization and has privileges to perform
replication in a BiHA cluster. Before you start initializing your
cluster, you must choose the authentication method for the biha_replication_user
role and make the required preparations based on your choice.
If you do not configure authentication using any of the methods listed below, you will be unable to add followers to your BiHA cluster.
BiHA supports the following ways to configure the
biha_replication_user authentication:
biha_replication_user #
BiHA supports SSL for biha_replication_user
authentication that you can configure when initializing your cluster using
bihactl cluster init. For more information about protecting connections using SSL,
see Section 18.9.
SSL authentication takes the highest priority. When SSL is used, the password file is ignored.
The bihactl utility does not create
any authentication rules in pg_hba*.conf.
When SSL is used, the biha_replication_user role
is created without password.
When SSL is used, you must specify
--biha-ssl-mode, --root-cert,
--user-biha-cert, and --user-biha-key
options for biha_replication_user
authentication when executing bihactl cluster status
and bihactl cluster show-config commands.
To configure SSL authentication:
Prepare the following certificates in the PEM format:
root CA certificate
server certificate and key for user validation
certificate and key for biha_replication_user authentication
Place the files mentioned above on all nodes of your BiHA cluster.
It is recommended that the certificate files are located in the same directory on all cluster nodes.
The next steps depend on the way you set up your BiHA cluster:
When initializing a BiHA cluster from scratch, execute the bihactl cluster init command specifying all required SSL options. For example:
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\
--server-cert=/path/to/server.crt \
--server-key=/path/to/server.key \
--user-biha-cert=/path/to/client.crt \
--user-biha-key=/path/to/client.key \
--root-cert=/path/to/ca.crt \
--biha-ssl-mode=verify-full
To add a follower, execute bihactl node add command
specifying only --biha-ssl-mode,
--root-cert, --user-biha-cert, and
--user-biha-key options, as server certificates are
transferred via backup. For example:
bihactl node add \ --biha-node-id=2 \ --host=node_2\ --port=node_port_number\ --biha-port=biha_port_number\ --use-leader "host=leader_hostport=leader_portbiha-port=leader_biha_port" \ --pgdata=follower_PGDATA_directory\ --user-biha-cert=/path/to/client.crt\ --user-biha-key=/path/to/client.key\ --root-cert=/path/to/ca.crt\ --biha-ssl-mode=verify-full
When converting your existing cluster with SSL into a BiHA cluster,
execute the bihactl cluster init --convert
command specifying only --biha-ssl-mode,
--root-cert, --user-biha-cert, and
--user-biha-key options. For example:
bihactl cluster init --convert \
--biha-node-id=1 \
--host=node_1 \
--port=node_port_number \
--biha-port=biha_port_number \
--nquorum=number_of_nodes \
--pgdata=leader_PGDATA_directory \
--user-biha-cert=/path/to/client.crt \
--user-biha-key=/path/to/client.key \
--root-cert=/path/to/ca.crt \
--biha-ssl-mode=verify-full
To convert your existing standby node with SSL into a follower,
execute the bihactl node add --convert-standby
specifying only --biha-ssl-mode,
--root-cert, --user-biha-cert, and
--user-biha-key options. For example:
bihactl node add --convert-standby \ --biha-node-id=2 \ --host=node_2\ --port=node_port_number\ --biha-port=biha_port_number\ --use-leader "host=leader_hostport=leader_portbiha-port=leader_biha_port" \ --pgdata=follower_PGDATA_directory\ --user-biha-cert=/path/to/client.crt--user-biha-key=/path/to/client.key\ --root-cert=/path/to/ca.crt\ --biha-ssl-mode=verify-full
When converting your existing cluster without SSL into a BiHA cluster, execute the bihactl cluster init --convert specifying all required SSL options. For example:
bihactl cluster init --convert \
--biha-node-id=1 \
--host=host \
--port=node_port_number \
--biha-port=biha_port_number \
--nquorum=number_of_nodes \
--pgdata=leader_PGDATA_directory \
--server-cert=/path/to/server.crt \
--server-key=/path/to/server.key \
--user-biha-cert=/path/to/client.crt \
--user-biha-key=/path/to/client.key \
--root-cert=/path/to/ca.crt \
--biha-ssl-mode=verify-full
To convert your existing standby node without SSL into a follower, execute the bihactl node add --convert-standby specifying all required SSL options. For example:
bihactl node add --convert-standby \ --biha-node-id=2 \ --host=host\ --port=node_port_number\ --biha-port=biha_port_number\ --use-leader "host=leader_hostport=leader_portbiha-port=leader_biha_port" \ --pgdata=follower_PGDATA_directory\ --server-cert=/path/to/server.crt\ --server-key=/path/to/server.key\ --user-biha-cert=/path/to/client.crt\ --user-biha-key=/path/to/client.key\ --root-cert=/path/to/ca.crt\ --biha-ssl-mode=verify-full
When initialization is finished, check the pg_hba.biha.conf
file to ensure that the cert authentication method is used.
If required, you can later modify some SSL-related values using special configuration parameters.
To avoid storing the biha_replication_user
password in the pgpass password file, you can
use PGPASSWORD and
BIHA_REPLICATION_PASSWORD environment variables. The password
must be the same in both environment variables and on all nodes of your
BiHA cluster.
When you initialize the cluster using
the bihactl bihactl cluster init command,
the bihactl utility takes the password from
BIHA_REPLICATION_PASSWORD.
When you add nodes to the cluster using
the bihactl node add command,
the bihactl utility takes the password from
PGPASSWORD.
To use authentication via the pgpass password file,
you must specify the password for the biha_replication_user
role in password files of all nodes of your BiHA
cluster. When you initialize the cluster using
the bihactl cluster init command
and then add nodes using the bihactl node add command,
the bihactl utility takes the password from the
password file.
To ensure connection between the leader and followers, the password of
the biha_replication_user role
must be the same on all nodes of the BiHA cluster.
You can specify the password using one of the following approaches:
The secure and recommended approach is to add a separate line for each node:
echo 'hostname:port:biha_db:biha_replication_user:password' >> ~/.pgpass echo 'hostname:port:replication:biha_replication_user:password' >> ~/.pgpass
The simple approach is to add a single line for all nodes:
echo '*:*:*:biha_replication_user:password' >> ~/.pgpass
To set up a BiHA cluster from scratch, perform the following procedures.
Prerequisites
On all nodes of your future cluster,
install the postgrespro-ent-17-contrib
package.
Do not create a database instance.
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.
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.
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,
configure quorum-based synchronous replication,
and configure SSL authentication
for the biha_replication_user role.
(Optional) Specify the password for the
biha_replication_user
role and re-enter the password for verification.
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.
Start the DBMS using pg_ctl:
pg_ctl start -Dleader_PGDATA_directory-lleader_log_file
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
Adding a follower node
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, an error may occur during node backup.
By default, pg_basebackup is used when adding follower nodes. If you want to add a follower using pg_probackup, refer to the corresponding instruction.
Ensure that the leader node is in the LEADER_RO or
LEADER_RW state.
Ensure that you configure the biha_replication_user role
authentication using one of the
supported methods.
Ensure that the data directory (PGDATA) of the node
that you want to add as a follower is empty or absent.
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
A backup of the leader node is created by means of pg_basebackup. Besides, postgresql.conf and pg_hba.conf files are modified.
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.
Start the DBMS using pg_ctl:
pg_ctl start -Dfollower_PGDATA_directory-lfollower_log_file
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
Convert your existing Postgres Pro Enterprise 17 cluster with streaming replication and a configured database instance into a BiHA cluster. After conversion, the primary node of the existing cluster becomes the leader node, and standby nodes become follower nodes.
Prerequisites
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.
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
Stop the existing primary node using pg_ctl:
pg_ctl stop -D primary_PGDATA_directory
Execute the bihactl cluster init command with the --convert option:
bihactl cluster 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,
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.10.
(Optional) Specify the password for the
biha_replication_user
role and re-enter the password for verification.
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.
Start the DBMS using pg_ctl:
pg_ctl start -Dleader_PGDATA_directory-lleader_log_file
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
Converting the existing standby node into the follower node
Ensure that you configure the biha_replication_user role
authentication using one of the
supported methods.
Stop the existing standby node using pg_ctl:
pg_ctl stop -D standby_PGDATA_directory
Execute the bihactl node add command with the --convert-standby option:
bihactl node add --convert-standby \ --biha-node-id=2 \ --host=host\ --port=PostgresPro_port\ --biha-port=5435 \ --use-leader "host=leader_hostport=leader_portbiha-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.conffollower_PGDATA_directory/pg_biha/biha.state
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.
Start the DBMS using pg_ctl:
pg_ctl start -Dfollower_PGDATA_directory-lfollower_log_file
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
If your existing Postgres Pro Enterprise 17 server with a configured database has only one node, you can convert it into the leader and then add more nodes to your BiHA cluster using the bihactl node add command.
Prerequisites
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.
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
Stop the existing node using pg_ctl:
pg_ctl stop -D server_PGDATA_directory
Execute the bihactl cluster init command with the --convert option:
bihactl cluster 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,
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.10.
(Optional) Specify the password for the
biha_replication_user
role and re-enter the password for verification.
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.
Start the DBMS using pg_ctl:
pg_ctl start -Dleader_PGDATA_directory-lleader_log_file
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
Adding a follower node
By default, pg_basebackup is used when adding follower nodes. If you want to add a follower using pg_probackup, refer to the corresponding instruction.
Ensure that the leader node is in the LEADER_RO
or LEADER_RW state.
Ensure that you configure the biha_replication_user role
authentication using one of the
supported methods.
Ensure that the data directory (PGDATA) of the node
that you want to add as a follower is empty or absent.
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
A backup of the leader node is created by means of pg_basebackup. 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.
Start the DBMS using pg_ctl:
pg_ctl start -Dfollower_PGDATA_directory-lfollower_log_file
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
The referee node participates in elections and helps to manage split-brain issues.
It is recommended to disable autovacuum before you start adding the referee node. When the referee is added, you can re-enable autovacuum.
You can use only pg_basebackup when adding the referee node to your cluster.
By default, only the biha_db database and system
tables are copied to the referee node.
The postgres database and user data are not copied.
If you need the postgres database on your referee node,
specify the --referee-with-postgres-db option.
To set up a referee node:
Ensure that the data directory (PGDATA) of the node
that you want to add as the referee is empty or absent.
Execute the bihactl node add command with the relevant value of the --mode option:
bihactl node add \
--biha-node-id=3 \
--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=referee_PGDATA_directory \
--mode=referee
or
bihactl node add \
--biha-node-id=3 \
--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=referee_PGDATA_directory \
--mode=referee_with_wal
Check the shared_buffers configuration parameter of the referee.
If it is too high, set the value to the default 128 MB.
Using pg_ctl, start the Postgres Pro instance where you have set up the referee:
pg_ctl start -D referee_PGDATA_directory
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
To extend high availability capabilities with a proxy server and a connection pooler functionality, you can enable the proxima extension while setting up your BiHA cluster.
You can also manage proxima in your existing BiHA cluster. For more information, see Managing proxima.
proxima is not installed on the referee node.
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.
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.
When your BiHA cluster is ready, you can modify the proxima configuration parameters.
You can either create your GDBiHA cluster from scratch, or convert your your existing Postgres Pro Enterprise 17 cluster with streaming replication and a configured database instance into a GDBiHA cluster.
In this example, you will create a GDBiHA cluster consisting of six nodes distributed across two segments.
Prerequisites
If you set up your GDBiHA cluster from scratch,
on all nodes of your future cluster,
install the postgrespro-ent-17-contrib
package.
Do not create a database instance.
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.
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.
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 17 cluster, additionally specify the --convert option.
(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.
Start the DBMS using pg_ctl:
pg_ctl start -Dleader_PGDATA_directory-lleader_log_file
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.
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
When adding follower nodes, remember that you must distribute them between two
segments. It is recommended to first add two followers to the default 111
segment, and then add three followers to the segment that you created manually.
Ensure that the leader node is in the LEADER_RO or
LEADER_RW state.
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 17 cluster, additionally specify the --convert-standby option.
A backup of the leader node is created by means of pg_basebackup. Besides, postgresql.conf and pg_hba.conf files are modified.
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.
Start the DBMS using pg_ctl:
pg_ctl start -Dfollower_PGDATA_directory-lfollower_log_file
Check the node status in the biha.status_v view:
SELECT * FROM biha.status_v;
Repeat the steps above to create all the required followers.
When all nodes are ready, check the cluster status in the biha.super_status_v view:
SELECT * FROM biha.super_status_v;
When initializing your BiHA cluster, you can enable SSL for the cluster service connections by means of the --use-ssl option. To enable or disable SSL in the initialized BiHA cluster, use the procedure described in Managing SSL for Service Connections.
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.
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 -keyoutpath_to_key-outpath_to_certificate-sha256 -daysperiod_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
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
When you initialize a BiHA cluster with bihactl cluster init, specify the --use-ssl option:
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
--use-ssl
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;
The magic string is a special string generated automatically when you initiate a BiHA cluster. It contains the data required to connect follower nodes to the leader node.
You can use the magic string in BiHA cluster setup scripts, as well as to avoid entering the leader node connection data manually when adding follower nodes.
Here is an example of how to use the magic string:
Initialize the BiHA cluster using bihactl cluster init:
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
The bihactl cluster init command output represents the magic string. The magic string example looks as follows:
dmVyc2lvbj0xIGhvc3Q9bG9jYWxob3N0IHBvcnQ9NTQzMiBiaWhhLXBvcnQ9NTQzMw==
Copy and save the command output.
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 node add \ --biha-node-id=2 \ --host=host\ --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.
If required, you can use pg_probackup instead of pg_basebackup to add followers.
Before you begin adding a follower, ensure that you created the BiHA cluster leader by initializing from scratch or converting the existing primary node.
On the server where you want to host a follower, perform the following steps:
Install the pg-probackup-ent-17 package.
Create a Postgres Pro Enterprise instance by making a backup of the leader using the pg_probackup catchup command:
pg_probackup catchup \
--source-pgdata=/path/to/leader_PGDATA_directory \
--destination-pgdata=/path/to/follower_PGDATA_directory \
--backup-mode=FULL \
--stream \
--pgdatabase=biha_db \
--pghost=leader_host \
--pgport=leader_PostgresPro_port \
--pguser=biha_replication_user \
--remote-host=leader_host
Delete the pg_biha directory created by the previous command:
rm -rfd follower_PGDATA_directory/pg_biha
Convert the created Postgres Pro Enterprise instance into a follower using the bihactl node add command with the --convert-standby option:
bihactl node add --convert-standby \
--biha-node-id=follower_ID \
--host=follower_host \
--biha-port=follower_BiHA_port \
--pgdata=follower_PGDATA_directory \
--magic-string=magic_string_to_connect_to_leader
Start the follower using pg_ctl:
pg_ctl start -Dfollower_PGDATA_directory-lfollower_log_file