12.1. Node management functions

BDR and UDR use functions to manage the addition and removal of nodes and related replication control functions. See Node management for more on how to manage BDR.

The following functions exist to manage nodes:

Table 12-1. Node management functions

UDR/BDRFunctionReturn TypeDescription
UDR bdr.bdr_subscribe(local_node_name, subscribe_to_dsn, node_local_dsn, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default'], synchronize bdr_sync_type DEFAULT 'full') voidSubscribes to changes made on another node. See Node management function examples.
UDR bdr.bdr_unsubscribe(local_node_name) voidRemoves a previously created UDR subscription.
BDR bdr.bdr_group_create(local_node_name, node_external_dsn, node_local_dsn DEFAULT NULL, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) void Create the first node in a future cluster of bdr nodes.
BDR bdr.bdr_group_join(local_node_name, node_external_dsn, join_using_dsn, node_local_dsn DEFAULT NULL, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) void Join this database to a cluster of existing bdr nodes. This will initiate connections to and from all nother nodes.
BDR bdr.bdr_part_by_node_names(p_nodes text[]) void Removes all the nodes - identified by the node names in the array. All the remaining nodes in the cluster have to be reachable for this to succeed.
BDR/UDR bdr.bdr_node_join_wait_for_ready() void Wait till all in-progress node joins have completed.
BDR/UDR bdr.bdr_apply_pause() void Temporarily stop applying changes from remote nodes to the local node, until resume is requested with bdr.bdr_apply_resume(). Connections to the remote node(s) are retained but no data is read from them. The effects of pausing apply are not persistent, so replay will resume if PostgreSQL is restarted or the postmaster does crash recovery after a backend crash. Terminating individual backends using pg_terminate_backend will not cause replay to resume; nor will reloading the postmaster without a full restart. There is no option to pause replay from only one peer node.
BDR/UDR bdr.bdr_apply_resume() void Resume replaying changes from peer nodes after replay has been paused by bdr.bdr_apply_pause().
BDR bdr.bdr_replicate_ddl_command(cmd text) void Execute the SQL (usually DDL) cmd on the local node and queue it for extension on all peer nodes. This function is mainly for BDR internal use and bypasses some safety checks, use with caution.

12.1.1. bdr.bdr_subscribe

The function bdr.bdr_subscribe will create unidirectional connection between the local node and subscribe_to_dsn node.

Since: version 0.9.0.

The parameters are:

local_node_name

A string specifying the name of the new node (for identification purposes).

subscribe_to_dsn

Connection string of the remote node from which replication should be started.

node_local_dsn

Public connection string to the new local node. It is used during initialization.

apply_delay (optional)

Time (in milliseconds), the node will wait before applying changes incoming from from the remote node.

replication_sets (optional)

Text array of replication sets which should be replicated to the local node. Note that you need to assign individual tables to the replication sets on the remote node.

synchronize (optional)

What to synchronize (copy) during the node initialization. Currently supported values are full (the default) which means do full schema and data copy and none which means don't copy anything. Note that this can cause apply failures if the schemas of nodes differ.

If objects (tables, functions, types, views, etc) already exist on the local node, i.e. the node calling this function, and have the same names as objects on the upstream node being subscribed to, the subscribe may fail. This failure will be visible in the logs but will not result in any error being sent to the client that invoked the subscribe function. Use bdr.bdr_unsubscribe to remove a failed subscription.

12.1.2. Node management function examples

These examples show libpq connection strings without a host or hostadd.

To subscribe to a UDR group:

    SELECT bdr_bdr_subscribe(
       local_node_name := 'udrnode',
       subscribe_to_dsn := 'port=6000 dbname=udrdemo',
       node_local_dsn := 'port=6001 dbname=udrdemo');
   

To create a BDR group on 'node1':

    SELECT bdr_bdr_group_create(
       local_node_name := 'node1',
       node_external_dsn := 'port=5598 dbname=bdrdemo');
   

To join 'node2' to BDR group created above:

    SELECT bdr.bdr_group_join(
       local_node_name := 'node2',
       node_external_dsn := 'port=5559 dbname=bdrdemo',
       join_using_dsn := 'port=5558 dbname=bdrdemo');
   

To remove 'node2' from the BDR group created above:

   SELECT bdr.bdr_part_by_node_names('{node2}');
   

To see if your node is ready for replication (if you see a NULL result set, your node is ready):

   SELECT bdr.bdr_node_join_wait_for_ready();