bihactl is a command line utility that allows creating a BiHA cluster, changing its composition, as well as monitoring the cluster status and version.
For more information about the bihactl commands, see bihactl.
biha is a Postgres Pro extension that allows managing a BiHA cluster.
This section contains information about the biha extension configuration parameters, functions, and views.
The biha extension provides several configuration parameters described below that are specific to the BiHA cluster. In addition, biha uses the following Postgres Pro configuration parameters:
Parameters set automatically at the BiHA cluster setup: listen_addresses, port, shared_preload_libraries, wal_keep_size.
Parameters used by biha with their default values: hot_standby, max_replication_slots, max_slot_wal_keep_size, max_wal_senders, wal_level.
Parameters modified and managed by biha only: primary_conninfo, primary_slot_name, synchronous_standby_names.
When biha is loaded and configured, you cannot modify these parameters using ALTER SYSTEM. For more information, see Section 27.2.1.
When setting the cluster configuration parameters, you must ensure network reliability for the changes to affect all cluster nodes without any errors.
biha.autorewind (boolean)
#
An optional parameter that controls the automatic rewind policy
for that node, against which the pg_rewind must be
executed.
For example, for the old leader when synchronizing it with the new leader.
The default value is false meaning that
the automatic rewind is not performed. When the value is set to
true, the automatic rewind is performed after the
error that usually causes the NODE_ERROR state of the
node. The automatic rewind is performed if it may complete successfully
meaning that preliminary launching of pg_rewind
with the --dry-run option was a success. If the
automatic rewind fails, the node is transferred to the
NODE_ERROR state. In this case, you can find the
actual rewind state of the node in the biha.state
file as described in Section 27.3.6.
Note that the rewind may cause the loss of some node WAL records.
biha.callbacks_timeout (integer)
#
Sets time for execution of all callbacks for a single event,
in milliseconds. The default value is 10000 (10 seconds).
The minimum value is 1000 (1 second).
The value of the biha.callbacks_timeout parameter can
be different for different nodes. Changing the value for the leader
does not change it for the followers.
biha.can_be_leader (boolean)
#
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.
A node that cannot become the leader may have the largest WAL. In this case,
if elections are required, those nodes that can stand as candidates attempt
to receive missing data from that node. If they succeed, one of these
nodes becomes the leader. If they fail to receive missing data, the automatic rewind
process is launched on the node that cannot become the leader. If
biha.autorewind is not enabled,
the node state changes to NODE_ERROR.
biha.can_vote (boolean)
#
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.
biha.flw_ro (boolean)
#
Determines whether a follower is available for read operations. If set to
off, reading from this follower is prohibited. The
default value is on.
biha.heartbeat_max_lost (integer)
#
Specifies the maximum number of heartbeats that can be missed before the
node is considered offline. This parameter can be set with the
biha.set_heartbeat_max_lost function. The default
value is 10.
biha.heartbeat_send_period (integer)
#
Specifies the heartbeat sending frequency, in milliseconds. This
parameter can be set with the biha.set_heartbeat_send_period
function. The default value is 1000.
biha.host (text)
#Specifies the host of the cluster node. This parameter is unique for each node of the cluster. For the first node it is set at cluster initialization, for other nodes it is set when adding them to the cluster. It is not recommended to modify this parameter.
biha.id (integer)
#Specifies the ID of the high-availability cluster node. This parameter is unique for each node of the cluster. For the first node it is set at cluster initialization, for other nodes it is set when adding them to the cluster. It is not recommended to modify this parameter.
biha.minnodes (integer)
#
Specifies the minimum number of operational nodes for the leader node to
be open for write transactions. This parameter can be set with
the biha.set_minnodes function. If you do not specify
the --minnodes option in bihactl init command,
the biha.minnodes value equals the biha.nquorum value.
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 minnodes value must be 2.
Nodes with the biha.can_vote parameter set
to false are ignored.
biha.no_wal_on_follower (integer)
#
Specifies the timeout of the replication slot position advancement,
in milliseconds.
This parameter can be set with the
biha.set_no_wal_on_follower function. The default
value is 20000.
If the timeout is reached for the follower, the leader node
notices that the follower does not receive WAL. If at the same time the
biha.heartbeat_max_lost * biha.heartbeat_send_period
value is exceeded, the leader considers the follower offline.
The parameter is also used when you set the leader manually as the selected node is promoted after it stops receiving WAL from the old leader.
biha.node_priority (integer)
#
Sets the node priority in a synchronous cluster, in seconds. 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.
The default value is -1, meaning that the parameter is ignored.
A cluster is considered synchronous if all nodes of this cluster
are synchronous, i.e.all cluster nodes are
listed in the synchronous_standby_names parameter.
For asynchronous clusters, the parameter is ignored.
biha.nquorum (integer)
#Specifies the number of nodes, which must vote for the new leader node if the current leader is down. This parameter can be set with the biha.set_nquorum function.
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 minnodes value must be 2.
Nodes with the biha.can_vote parameter set
to false are ignored.
biha.port (integer)
#Specifies the port used to exchange service information between nodes. This parameter is required to establish a connection with the cluster. It is not recommended to modify this parameter.
biha.sync_standbys_min (integer)
#
Specifies the minimum number of synchronous follower nodes that must be
available for the leader node to continue operation. This parameter can
be set with the biha.set_sync_standbys_min function.
The value must be lower than --sync-standbys and cannot be negative.
The default value is -1, meaning that the parameter is
ignored. If the parameter 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.
Both the biha.sync_standbys_min parameter and the
biha.set_sync_standbys_min function can operate only
if you set the --sync-standbys-min option when initializing the
BiHA cluster by means of the
bihactl init command.
biha.BihaLog_log_level (enum)
#
Specifies the logging level to provide general information about the
operation of biha components. The default
value is LOG.
biha.BcpTransportDebug_log_level (enum)
#
Specifies the logging level to provide debugging information about the
control channel operation. The default value is DEBUG4.
biha.BcpTransportDetails_log_level (enum)
#
Specifies the logging level to provide detailed information about the
control channel operation. The default value is DEBUG4.
biha.BcpTransportLog_log_level (enum)
#
Specifies the logging level to provide general information about the
control channel operation. The default value is DEBUG4.
biha.BcpTransportWarn_log_level (enum)
#
Specifies the logging level to provide warnings of likely problems in
the control channel. The default value is DEBUG4.
biha.NodeControllerDebug_log_level (enum)
#
Specifies the logging level to provide debugging information about the
node controller operation. The default value is DEBUG4.
biha.NodeControllerDetails_log_level (enum)
#
Specifies the logging level to provide detailed information about the
node controller operation. The default value is DEBUG4.
biha.NodeControllerLog_log_level (enum)
#
Specifies the logging level to provide general information about the
node controller operation. The default value is DEBUG4.
biha.NodeControllerWarn_log_level (enum)
#
Specifies the logging level to provide warnings of likely problems in
the node controller. The default value is DEBUG4.
All functions listed below should be called from the biha_db
database, for example:
psql biha_db -c "select biha.set_leader(2)"
biha.get_magic_string () returns string
#Generates a magic string for the cluster node.
biha.remove_node (id integer) returns boolean
#Removes the node from the cluster. Before removing, the node must be stopped. This function can only be called on the leader node.
biha.set_leader (id integer) returns boolean
#Sets the leader node manually. It is recommended to call this function on the node that you want to set as the new leader.
Calling the biha.set_leader function on the current
leader is not recommended.
If you call the function on the current
leader in the LEADER_RW state, in case of a successful
switchover request, there may be not enough time for the request result
to be sent to the client before the current leader reboots for demotion.
biha.config () returns setof record
#
Returns the cluster configuration values: id,
term, nquorum,
minnodes, heartbeat_send_period,
heartbeat_max_lost, no_wal_on_follower,
sync_standbys_min, priority,
can_be_leader, can_vote.
biha.set_heartbeat_max_lost (integer) returns boolean
#Sets the biha.heartbeat_max_lost value. This function can be called only from the leader node and changes the parameter on all nodes. You do not need to restart the cluster for the changes to take effect.
biha.set_heartbeat_send_period (integer) returns boolean
#Sets the biha.heartbeat_send_period value, in milliseconds. This function can be called only from the leader node and changes the parameter on all nodes. You do not need to restart the cluster for the changes to take effect.
biha.set_no_wal_on_follower (integer) returns boolean
#Sets the biha.no_wal_on_follower value, in milliseconds. This function can be called only from the leader node and changes the parameter on all nodes. You do not need to restart the cluster for the changes to take effect.
biha.set_minnodes (integer) returns boolean
#Sets the biha.minnodes value. This function can be called only from the leader node and changes the parameter on all nodes. You do not need to restart the cluster for the changes to take effect.
biha.set_nquorum (integer) returns boolean
#Sets the biha.nquorum value. This function can be called only from the leader node and changes the parameter on all nodes. You do not need to restart the cluster for the changes to take effect.
biha.set_nquorum_and_minnodes (integer, integer) returns boolean
#Sets the biha.nquorum and biha.minnodes values. This function can be called only from the leader node and changes the parameters on all nodes. You do not need to restart the cluster for the changes to take effect.
biha.set_sync_standbys_min (integer) returns boolean
#
Sets the biha.sync_standbys_min
value and changes the MIN field value of
the synchronous_standby_names parameter accordingly if required.
This function can be called only from the leader node
and changes the parameter on all nodes. You do not need to restart the
cluster for the changes to take effect.
Both the biha.sync_standbys_min
parameter and the biha.set_sync_standbys_min function
can operate only if you set the --sync-standbys-min option
when initializing the BiHA cluster by means of the
bihactl init command.
biha.nodes () returns setof record
#
Defines the biha.nodes_v view, which
is described in detail in the biha.nodes_v
section.
biha.status () returns setof record
#
Defines the biha.status_v view, which
is described in detail in the biha.status_v
section. If the node does not respond when trying to display the view,
try the same request on any other node to learn the actual state of
cluster nodes.
NODE_ERROR State #biha.error_details () returns setof record
#
Returns the description of why the node transferred to the
NODE_ERROR state. The returned record contains the
type of the error, its details, the place it occurred specifying
begin_lsn, end_lsn, and identifier
of the current and the next timeline, as well as
replay_lsn.
biha.register_callback (event text, func text, database text, executor text, priority integer) returns integer
#
Adds a new callback and returns its unique ID. This function
can only be called from the leader node
in the LEADER_RW state.
The new callback will be replicated to the followers.
On the biha side, there is no check that
func exists in database. If the
specified function does not exist, the callback fails.
See Registering Callbacks for the example of
using the biha.register_callback function.
Table 27.3. Variable Definitions
| Name | Type | Description |
|---|---|---|
event | text | Event of the BiHA cluster that triggers a callback. For more information about events and corresponding callback types, see Callback Types. |
func | text |
Name of the SQL function that biha executes
when event happens. This function
must be located in database, otherwise it
cannot be executed.
|
database | text | Database where func is executed.
|
executor | text |
User that executes |
priority | integer |
The lower the value, the sooner the callback is
executed. This parameter is optional. The default value
is 0.
|
biha.unregister_callback(callback_id)
#
Deletes a callback. This function can only be called on the leader node
in the LEADER_RW state.
See Unregistering Callbacks for the example of
using the biha.unregister_callback function.
biha.nodes_v #
This view displays the connection status of nodes in the cluster.
For the node that the view is queried on, the following columns contain
NULL: state, since_conn_start,
conn_count.
Table 27.4. The biha.nodes_v view
| Column Name | Description |
|---|---|
id | The node ID. |
host | The host of the node. |
port | The port of the node. |
state |
The connection state of the node. This column may contain one of the
following values: ACTIVE,
CONNECTING, IDLE, or
INIT.
|
since_conn_start | The time since the node connection. |
conn_count | The number of times the node was connected since the start of the cluster. |
biha.status_v #This view displays the state of nodes in the cluster.
Table 27.5. The biha.status_v View
| Column Name | Description |
|---|---|
id | The node ID. |
leader_id | The leader node ID. |
term | The term of the node. This is used for the purposes of the leader election. |
online | Shows whether the node is online. |
state |
The state of the node. This column may contain one of the following values:
|
last_known_state | The last known state of the node. |
since_last_hb | The time since the last received heartbeat message. |