This page in other versions: 0.9 / 1.0

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 bdr.bdr_subscribe.
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. This function must be run on a node that is not being removed.
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/UDR bdr.bdr_apply_is_paused() boolean Report whether replay is paused (e.g. with bdr.bdr_apply_pause()). A false return does not mean replay is actually progressing, only that it's not intentionally paused.
BDR/UDR 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 useful mainly for replicating DDL in an UDR setup where the transparent DDL replication is not available. The same limitations apply to this function as to DDL run directly by the user, except that DDL not normally replicated by BDR will be replicated if run with this function; see DDL replication. References to objects in DDL must be fully schema-qualified (e.g. public.mytable not just mytable), otherwise the error no schema has been selected to create in will be emitted.
BDR pg_xlog_wait_remote_apply(lsn pg_lsn, pid integer) void Wait until the replication connection with process id pid (or all connections if pid is 0) in pg_stat_replication has replayed WAL up to at least lsn. Typically used with pg_current_xlog_insert_location() as the target LSN. (This function was added to PostgreSQL 9.4 by the BDR patches and is not part of the BDR extension as such.)
BDR pg_xlog_wait_remote_receive(lsn pg_lsn, pid integer) void Same as pg_xlog_wait_remote_receive(...), but returns as soon as the remote confirms it has received the changes, not necessarily applied them.

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();