Step 5 - Creating the PGD cluster v4.3.8

Creating the PGD cluster

• Create connection strings for each node.
  For each node, create a connection string that will allow PGD to perform replication.

  The connection string is a key/value string that starts with host= and the IP address of the host (or, if you have resolvable named hosts, the name of the host).

  That's followed by the name of the database: dbname=bdrdb. (The bdrdb database was created while installing the software.)

  We recommend you also add the port number of the server to your connection string as port=5444 for EDB Postgres Advanced Server and port=5432 for EDB Postgres Extended and community PostgreSQL.

• Prepare the first node. To create the cluster, log into the bdrdb database on one of the nodes.

• Create the first node.
  Run bdr.create_node and give the node a name and its connection string where other nodes can connect to it.
  • Create the top-level group. Create a top-level group for the cluster with bdr.create_node_group, giving it a single parameter: the name of the top-level group.
  • Create a subgroup. Create a subgroup as a child of the top-level group with bdr.create_node_group, giving it two parameters: the name of the subgroup and the name of the parent (and top-level) group. This sequence initializes the first node.

• Add the second node.
  • Create the second node.
    Log into another initialized node's bdrdb database. Run bdr.create_node and give the node a different name and its connection string where other nodes can connect to it.
  • Join the second node to the cluster. Next, run bdr.join_node_group, passing two parameters: the connection string for the first node and the name of the subgroup you want the node to join.

• Add the third node.
  • Create the third node. Log into another initialized node's bdrdb database. Run bdr.create_node and give the node a different name and its connection string where other nodes can connect to it.
  • Join the third node to the cluster. Next, run bdr.join_node_group, passing two parameters: the connection string for the first node and the name of the subgroup you want the node to join.

Worked example

So far, this example has:

• Created three hosts.
• Installed a Postgres server on each host.
• Installed Postgres Distributed on each host.
• Configured the Postgres server to work with PGD on each host.

To create the cluster, tell the host-one Postgres instance that it's a PGD node (node-one) and create PGD groups on that node. Then tell the host-two and host-three Postgres instances that they're PGD nodes (node-two and node-three) and that they should join a group on node-one.

Create connection strings for each node

Calculate the connection strings for each of the nodes in advance. Following are the connection strings for this 3-node example:

Preparing the first node

Log into the host-one Postgres server.

ssh admin@host-one
sudo -iu enterprisedb psql bdrdb

Create the first node

Call the bdr.create_node function to create a node, passing it the node name and a connection string that other nodes can use to connect to it.

select bdr.create_node('node-one','host=host-one dbname=bdrdb port=5444');

Create the top-level group

Call the bdr.create_node_group function to create a top-level group for your PGD cluster. Passing a single string parameter creates the top-level group with that name. For this example, create a top-level group named pgd:

select bdr.create_node_group('pgd');

Create a subgroup

Using subgroups to organize your nodes is preferred as it allows services like PGD Proxy, which you'll configured later in this example, to coordinate their operations. In a larger PGD installation, multiple subgroups can exist providing organizational grouping that enables geographical mapping of clusters and localized resilience. For that reason, this example creates a subgroup for the first nodes to enable simpler expansion and use of PGD Proxy.

Call the bdr.create_node_group function again to create a subgroup of the top-level group. The subgroup name is the first parameter, and the parent group is the second parameter. This example creates a subgroup dc1 as a child of pgd:

select bdr.create_node_group('dc1','pgd');

Add the second node

Log into the host-two Postgres server:

ssh admin@host-two
sudo -iu enterprisedb psql bdrdb

Create the second node

Call the bdr.create_node function to create this node, passing it the node name and a connection string that other nodes can use to connect to it:

select bdr.create_node('node-two','host=host-two dbname=bdrdb port=5444');

Join the second node to the cluster

Using bdr.join_node_group, you can ask node-two to join the node-one dc1 group. The function takes as a first parameter the connection string of a node already in the group. It takes the group name as a second parameter.

select bdr.join_node_group('host=host-one dbname=bdrdb port=5444','dc1');

Add the third node

Log into the host-three Postgres server.

ssh admin@host-three
sudo -iu enterprisedb psql bdrdb

Create the third node

Call the bdr.create_node function to create this node, passing it the node name and a connection string that other nodes can use to connect to it:

select bdr.create_node('node-three','host=host-three dbname=bdrdb port=5444');

Join the third node to the cluster

Using bdr.join_node_group, you can ask node-three to join the node-one dc1 group. The function takes as a first parameter the connection string of a node already in the group. It takes the group name as a second parameter.

select bdr.join_node_group('host=host-one dbname=bdrdb port=5444','dc1');

These steps have now created a PGD cluster.