Node management interfaces v5

You can add and remove nodes dynamically using the SQL interfaces.

`bdr.alter_node_group_option`

This function modifies a PGD node group configuration.

Synopsis

bdr.alter_node_group_option(node_group_name text,
    config_key text,
    config_value text)

Parameters

node_group_name — Name of the group to change.
config_key — Key of the option in the node group to change.
config_value — New value to set for the given key.
config_value is parsed into the data type appropriate for the option.

The table shows the group options that can be changed using this function. Some parameters can be applied only to the top-level node group. For these parameters, the Groups column contains Top. Some parameters can be applied to the top-level node group and subgroups. For these parameters, the Groups column contains All. When a parameter can be applied only to subgroups, the Groups column contains Sub.

Name	Type	Groups	Description
`apply_delay`	`interval`	All	How long nodes wait to apply incoming changes. This option is useful mainly to set up a special subgroup with delayed subscriber-only nodes. Don't set this on groups that contain data nodes or on the top-level group. Default is `0s`.
`check_constraints`	`boolean`	Top	Whether the apply process checks the constraints when writing replicated data. We recommend keeping the default value or you risk data loss. Valid values are `on` or `off`. Default is `on`.
`default_commit_scope`	`text`	All	The commit scope to use by default, initially the `local` commit scope. This option applies only to the top-level node group. You can use individual rules for different origin groups of the same commit scope. See Origin groups for more details.
`enable_proxy_routing`	`boolean`	All	Where `pgd-proxy` through the group leader is enabled for given group. Valid values are `on` or `off`. Default is `off`.
`enable_raft`	`boolean`	Sub	Whether group has its own Raft consensus. This option is necessary for setting `enable_proxy_routing` to `on`. This option is always `on` for the top-level group. Valid values are `on` or `off`. Default is `off` for subgroups.
`enable_wal_decoder`	`boolean`	Top	Enables/disables the decoding worker process. You can't enable the decoding worker process if `streaming_mode` is already enabled. Valid values are `on` or `off`. Default is `off`.
`location`	`text`	All	Information about group location. This option is purely metadata for monitoring. Default is `''` (empty string).
`num_writers`	`integer`	Top	Number of parallel writers for the subscription backing this node group. Valid values are `-1` or a positive integer. `-1` means the value specified by the GUC `bdr.writers_per_subscription` is used. `-1` is the default.
`route_reader_max_lag`	`integer`	All	Maximum lag in bytes for a node to be considered a viable read-only node. Currently reserved for future use.
`route_writer_max_lag`	`integer`	All	Maximum lag in bytes of the new write candidate to be selected as write leader. If no candidate passes this, no writer is selected. Default is `-1`.
`route_writer_wait_flush`	`boolean`	All	Whether to switch if PGD needs to wait for the flush. Currently reserved for future use.
`streaming_mode`	`text`	Top	Enables/disables streaming of large transactions. When set to `off`, streaming is disabled. When set to any other value, large transactions are decoded while they're still in progress, and the changes are sent to the downstream. If the value is set to `file`, then the incoming changes of streaming transactions are stored in a file and applied only after the transaction is committed on upstream. If the value is set to `writer`, then the incoming changes are directly sent to one of the writers, if available. If parallel apply is disabled or no writer is free to handle streaming transactions, then the changes are written to a file and applied after the transaction is committed. If the value is set to `auto`, PGD tries to intelligently pick between `file` and `writer`, depending on the transaction property and available resources. You can't enable `streaming_mode` if the WAL decoder is already enabled. Default is `auto`. For more details, see Transaction streaming.

Return value

bdr.alter_node_group_option() returns VOID on success.

An ERROR is raised if any of the provided parameters is invalid.

Notes

You can examine the current state of node group options by way of the view bdr.node_group_summary.

This function passes a request to the group consensus mechanism to change the defaults. The changes made are replicated globally using the consensus mechanism.

The function isn't transactional. The request is processed in the background, so you can't roll back the function call. Also, the changes might not be immediately visible to the current transaction.

This function doesn't hold any locks.

`bdr.alter_node_interface`

This function changes the connection string (DSN) of a specified node.

Synopsis

bdr.alter_node_interface(node_name text, interface_dsn text)

Parameters

node_name — Name of an existing node to alter.
interface_dsn — New connection string for a node.

Notes

Run this function and make the changes only on the local node. This means that you normally execute it on every node in the PGD group, including the node that's being changed.

This function is transactional. You can roll it back, and the changes are visible to the current transaction.

The function holds lock on the local node.

`bdr.alter_node_option`

This function modifies the PGD node routing configuration.

Synopsis

bdr.alter_node_option(node_name text,
    config_key text,
    config_value text);

Parameters

node_name — Name of the node to change.
config_key — Key of the option in the node to change.
config_value — New value to set for the given key.

The node options you can change using this function are:

route_priority — Relative routing priority of the node against other nodes in the same node group. Default is '-1'.
route_fence — Whether the node is fenced from routing. When true, the node can't receive connections from PGD Proxy. Default is 'f' (false).
route_writes — Whether writes can be routed to this node, that is, whether the node can become write leader. Default is 't' (true) for data nodes and 'f' (false) for other node types.
route_reads — Whether read-only connections can be routed to this node. Currently reserved for future use. Default is 't' (true) for data and subscriber-only nodes, 'f' (false) for witness and standby nodes.
route_dsn — The dsn for the proxy to use to connect to this node. This option is optional. If not set, it defaults to the node's node_dsn value.

`bdr.alter_subscription_enable`

This function enables either the specified subscription or all the subscriptions of the local PGD node. This is also known as resume subscription. No error is thrown if the subscription is already enabled. Returns the number of subscriptions affected by this operation.

Synopsis

bdr.alter_subscription_enable(
    subscription_name name DEFAULT NULL,
    immediate boolean DEFAULT false
)

Parameters

subscription_name — Name of the subscription to enable. If NULL (the default), all subscriptions on the local node are enabled.
immediate — This parameter currently has no effect.

Notes

This function isn't replicated and affects only local node subscriptions (either a specific node or all nodes).

This function is transactional. You can roll it back, and the current transaction can see any catalog changes. The subscription workers are started by a background process after the transaction has committed.

`bdr.alter_subscription_disable`

This function disables either the specified subscription or all the subscriptions of the local PGD node. Optionally, it can also immediately stop all the workers associated with the disabled subscriptions. This is also known as pause subscription. No error is thrown if the subscription is already disabled. Returns the number of subscriptions affected by this operation.

Synopsis

bdr.alter_subscription_disable(
    subscription_name name DEFAULT NULL,
    immediate boolean DEFAULT false,
    fast boolean DEFAULT true
)

Parameters

subscription_name — Name of the subscription to disable. If NULL (the default), all subscriptions on the local node are disabled.
immediate — Used to force the action immediately, stopping all the workers associated with the disabled subscription. When this option is true, you can't run this function inside of the transaction block.
fast — This argument influences the behavior of immediate. If set to true (the default), it stops all the workers associated with the disabled subscription without waiting for them to finish current work.

Notes

This function isn't replicated and affects only local node subscriptions (either a specific subscription or all subscriptions).

This function is transactional. You can roll it back, and the current transaction can see any catalog changes. However, the timing of the subscription worker stopping depends on the value of immediate. If set to true, the workers receive the stop without waiting for the COMMIT. If the fast argument is set to true, the interruption of the workers doesn't wait for current work to finish.

`bdr.create_node`

This function creates a node.

Synopsis

bdr.create_node(node_name text,
                local_dsn text,
                node_kind DEFAULT NULL)

Parameters

node_name — Name of the new node. Only one node is allowed per database. Valid node names consist of lowercase letters, numbers, hyphens, and underscores.
local_dsn — Connection string to the node.
node_kind — One of data (the default), standby, subscriber-only, or witness. If you don't set this parameter, or if you provide NULL, the default data node kind is used.

Notes

This function creates a record for the local node with the associated public connection string. There can be only one local record, so once it's created, the function reports an error if run again.

This function is a transactional function. You can roll it back and the changes made by it are visible to the current transaction.

The function holds lock on the newly created node until the end of the transaction.

`bdr.create_node_group`

This function creates a PGD node group. By default, the local node joins the group as the only member. You can add more nodes to the group with bdr.join_node_group().

Synopsis

bdr.create_node_group(node_group_name text,
                      parent_group_name text DEFAULT NULL,
                      join_node_group boolean DEFAULT true,
                      node_group_type text DEFAULT NULL)

Parameters

node_group_name — Name of the new PGD group. As with the node name, valid group names must consist of only lowercase letters, numbers, and underscores.
parent_group_name — If a node subgroup is being created, this must be the name of the parent group. Provide NULL (the default) when creating the main node group for the cluster.
join_node_group — Determines whether the node joins the group being created. The default value is true. Providing false when creating a subgroup means the local node won't join the new group, for example, when creating an independent remote group. In this case, you must specify parent_group_name.
node_group_type — The valid values are NULL or subscriber-only. NULL (the default) is for creating a normal, general-purpose node group. subscriber-only is for creating subscriber-only groups whose members receive changes only from the fully joined nodes in the cluster but that never send changes to other nodes.

Notes

This function passes a request to the local consensus worker that's running for the local node.

The function isn't transactional. The creation of the group is a background process, so once the function finishes, you can't roll back the changes. Also, the changes might not be immediately visible to the current transaction. You can call bdr.wait_for_join_completion to wait until they are.

The group creation doesn't hold any locks.

`bdr.join_node_group`

This function joins the local node to an already existing PGD group.

Synopsis

bdr.join_node_group (
    join_target_dsn text,
    node_group_name text DEFAULT NULL,
    pause_in_standby boolean DEFAULT NULL,
    wait_for_completion boolean DEFAULT true,
    synchronize_structure text DEFAULT 'all'
)

Parameters

join_target_dsn — Specifies the connection string to an existing (source) node in the PGD group you want to add the local node to.
node_group_name — Optional name of the PGD group. Defaults to NULL, which tries to detect the group name from information present on the source node.
wait_for_completion — Wait for the join process to complete before returning. Defaults to true.
synchronize_structure — Set the kind of structure (schema) synchronization to do during the join. The default setting is all, which synchronizes the complete database structure, The other available setting is none, which doesn't synchronize any structure. However, it still synchronizes data (except for witness nodes, which by design don't synchronize data).
pause_in_standby — Optionally tells the join process to join only as a logical standby node, which can be later promoted to a full member. This option is deprecated and will be disabled or removed in future versions of PGD.

Warning

pause_in_standby is deprecated since BDR 5.0. The recommended way to create a logical standby is to set node_kind to standby when creating the node with bdr.create_node.

If wait_for_completion is specified as false, the function call returns as soon as the joining procedure starts. You can see the progress of the join in the log files and the bdr.event_summary information view. You can call the function bdr.wait_for_join_completion() after bdr.join_node_group() to wait for the join operation to complete. It can emit progress information if called with verbose_progress set to true.

Notes

This function passes a request to the group consensus mechanism by way of the node that the join_target_dsn connection string points to. The changes made are replicated globally by the consensus mechanism.

The function isn't transactional. The joining process happens in the background and you can't roll it back. The changes are visible only to the local transaction if wait_for_completion was set to true or by calling bdr.wait_for_join_completion later.

Node can be part of only a single group, so you can call this function only once on each node.

Node join doesn't hold any locks in the PGD group.

`bdr.part_node`

Removes (parts) the node from the PGD group but doesn't remove data from the node.

You can call the function from any active node in the PGD group, including the node that you're removing. However, once the node is parted, it can't part other nodes in the cluster.

Note

If you're parting the local node, you must set wait_for_completion to false. Otherwise, it reports an error.

Warning

This action is permanent. If you want to temporarily halt replication to a node, use bdr.alter_subscription_disable().

Synopsis

bdr.part_node (
    node_name text,
	wait_for_completion boolean DEFAULT true,
	force boolean DEFAULT false
)

Parameters

node_name — Name of an existing node to part.
wait_for_completion — If true, the function doesn't return until the node is fully parted from the cluster. Otherwise the function starts the parting procedure and returns immediately without waiting. Always set to false when executing on the local node or when using force.
force — Forces removal of the node on the local node. This sets the node state locally if consensus can't be reached or if the node-parting process is stuck.

Warning

Using force = true can leave the PGD group in an inconsistent state. Use it only to recover from failures in which you can't remove the node any other way.

Notes

This function passes a request to the group consensus mechanism to part the given node. The changes made are replicated globally by the consensus mechanism. The parting process happens in the background, and you can't roll it back. The changes made by the parting process are visible only to the local transaction if wait_for_completion was set to true.

With force set to true, on consensus failure, this function sets the state of the given node only on the local node. In such a case, the function is transactional (because the function changes the node state) and you can roll it back. If the function is called on a node that's already in process of parting with force set to true, it also marks the given node as parted locally and exits. This is useful only when the consensus can't be reached on the cluster (that is, the majority of the nodes are down) or if the parting process is stuck. But it's important to take into account that when the parting node that was receiving writes, the parting process can take a long time without being stuck. The other nodes need to resynchronize any missing data from the given node. The force parting completely skips this resynchronization and can leave the other nodes in an inconsistent state.

The parting process doesn't hold any locks.

`bdr.promote_node`

This function promotes a local logical standby node to a full member of the PGD group.

Synopsis

bdr.promote_node(wait_for_completion boolean DEFAULT true)

Notes

This function passes a request to the group consensus mechanism to change the defaults. The changes made are replicated globally by the consensus mechanism.

The function isn't transactional. The promotion process happens in the background, and you can't roll it back. The changes are visible only to the local transaction if wait_for_completion was set to true or by calling bdr.wait_for_join_completion later.

The promotion process holds lock against other promotions. This lock doesn't block other bdr.promote_node calls but prevents the background process of promotion from moving forward on more than one node at a time.

`bdr.switch_node_group`

This function switches the local node from its current subgroup to another subgroup in the same existing PGD node group.

Synopsis

bdr.switch_node_group (
    node_group_name text,
    wait_for_completion boolean DEFAULT true
)

Parameters

node_group_name — Name of the PGD group or subgroup.
wait_for_completion — Wait for the switch process to complete before returning. Defaults to true.

If wait_for_completion is specified as false, this is an asynchronous call that returns as soon as the switching procedure starts. You can see progress of the switch in logs and the bdr.event_summary information view or by calling the bdr.wait_for_join_completion() function after bdr.switch_node_group() returns.

Notes

This function passes a request to the group consensus mechanism. The changes made are replicated globally by the consensus mechanism.

The function isn't transactional. The switching process happens in the background and you can't roll it back. The changes are visible only to the local transaction if wait_for_completion was set to true or by calling bdr.wait_for_join_completion later.

The local node changes membership from its current subgroup to another subgroup in the same PGD node group without needing to part the cluster. The node's kind must match that of existing nodes in the target subgroup.

Node switching doesn't hold any locks in the PGD group.

Restrictions: Currently, the function allows switching only between a subgroup and its PGD node group. To effect a move between subgroups you need to make two separate calls: 1) switch from subgroup to node group and, 2) switch from node group to other subgroup.

`bdr.wait_for_join_completion`

This function waits for the join procedure of a local node to finish.

Synopsis

bdr.wait_for_join_completion(verbose_progress boolean DEFAULT false)

Parameters

verbose_progress — Optionally prints information about individual steps taken during the join procedure.

Notes

This function waits until the checks state of the local node reaches the target state, which was set by bdr.create_node_group, bdr.join_node_group, or bdr.promote_node.

`bdr.alter_node_group_config`

This function changes the configuration parameters of an existing PGD group. Options with NULL value (default for all of them) aren't modified.

Warning

This function exists only for compatibility with PGD4 and 3.7. Use bdr.alter_node_group_option instead.

Synopsis

bdr.alter_node_group_config(node_group_name text,
                            insert_to_update boolean DEFAULT NULL,
                            update_to_insert boolean DEFAULT NULL,
                            ignore_redundant_updates boolean DEFAULT NULL,
                            check_full_tuple boolean DEFAULT NULL,
                            apply_delay interval DEFAULT NULL,
                            check_constraints boolean DEFAULT NULL,
                            num_writers int DEFAULT NULL,
							enable_wal_decoder boolean DEFAULT NULL,
							streaming_mode text DEFAULT NULL,
                            default_commit_scope text DEFAULT NULL)

Parameters

Name	Description
`node_group_name`	Name of an existing PGD group. The local node must be part of the group.
`insert_to_update`	Reserved for backward compatibility.
`update_to_insert`	Reserved for backward compatibility. This option is deprecated and will be disabled or removed in future versions of PGD. Use `bdr.alter_node_set_conflict_resolver` instead.
`ignore_redundant_updates`	Reserved for backward compatibility.
`check_full_tuple`	Reserved for backward compatibility.
`apply_delay`	How long nodes wait to apply incoming changes. This parameter is useful mainly to set up a special subgroup with delayed subscriber-only nodes. Don't set this on groups that contain data nodes or on the top-level group. Default is `0s`.
`check_constraints`	Whether the apply process checks the constraints when writing replicated data. We recommend keeping this set to the default value or you risk data loss. Valid values are `on` or `off`. Default is `on`. Applies to top-level group only.
`num_writers`	Number of parallel writers for the subscription backing this node group. Valid values are `-1` or a positive integer. `-1` means the value specified by the GUC `bdr.writers_per_subscription` is used. `-1` is the default. Applies to top-level group only.
`enable_wal_decoder`	Enables/disables the decoding worker process. You can't enable the decoding worker process if `streaming_mode` is already enabled. Valid values are `on` or `off`. Default is `off`. Applies to top-level group only.
`streaming_mode`	Enables/disables streaming of large transactions. When set to `off`, streaming is disabled. When set to any other value, large transactions are decoded while they're still in progress, and the changes are sent to the downstream. If the value is set to `file`, then the incoming changes of streaming transactions are stored in a file and applied only after the transaction is committed on upstream. If the value is set to `writer`, then the incoming changes are directly sent to one of the writers, if available. If parallel apply is disabled or no writer is free to handle streaming transaction, then the changes are written to a file and applied after the transaction is committed. If the value is set to `auto`, PGD tries to intelligently pick between `file` and `writer`, depending on the transaction property and available resources. You can't enable `streaming_mode` if the WAL decoder is already enabled. For more details, see Transaction streaming. Applies to top-level group only.
`default_commit_scope`	The commit scope to use by default, initially the `local` commit scope. This parameter applies only to the top-level node group. You can use individual rules for different origin groups of the same commit scope. See Origin groups for more details.

Notes

This function passes a request to the group consensus mechanism to change the defaults. The changes made are replicated globally using the consensus mechanism.

The function isn't transactional. The request is processed in the background so you can't roll back the function call. Also, the changes might not be immediately visible to the current transaction.

This function doesn't hold any locks.

`bdr.drop_node_group`

This function drops an empty PGD node group. If there are any joined nodes in the group, the function will fail.

Synopsis

bdr.drop_node_group(node_group_name text)

Parameters

node_group_name — Name of the PGD group to drop.

Notes

This function passes a request to the group consensus mechanism to drop the group.
The function isn't transactional. The dropping process happens in the background, and you can't roll it back.

← Prev

Node management

↑ Up

PGD reference

Routing functions

Node management interfaces v5

bdr.alter_node_group_option

Synopsis

Parameters

Return value

Notes

bdr.alter_node_interface

Synopsis

Parameters

Notes

bdr.alter_node_option

Synopsis

Parameters

bdr.alter_subscription_enable

Synopsis

Parameters

Notes

bdr.alter_subscription_disable

Synopsis

Parameters

Notes

bdr.create_node

Synopsis

Parameters

Notes

bdr.create_node_group

Synopsis

Parameters

Notes

bdr.join_node_group

Synopsis

Parameters

Warning

Notes

bdr.part_node

Note

Warning

Synopsis

Parameters

Warning

Notes

bdr.promote_node

Synopsis

Notes

bdr.switch_node_group

Synopsis

Parameters

Notes

bdr.wait_for_join_completion

Synopsis

Parameters

Notes

bdr.alter_node_group_config

Warning

Synopsis

Parameters

Notes

bdr.drop_node_group

Synopsis

Parameters

Notes

← Prev

↑ Up

Next →

`bdr.alter_node_group_option`

`bdr.alter_node_interface`

`bdr.alter_node_option`

`bdr.alter_subscription_enable`

`bdr.alter_subscription_disable`

`bdr.create_node`

`bdr.create_node_group`

`bdr.join_node_group`

`bdr.part_node`

`bdr.promote_node`

`bdr.switch_node_group`

`bdr.wait_for_join_completion`

`bdr.alter_node_group_config`

`bdr.drop_node_group`