Step 5 - Creating the PGD cluster v5

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 a host= and the IP address of the host. (If you have resolvable named hosts, the name of the host is used instead of the IP address.)

  That's followed by the name of the database. In this case, use dbname=bdrdb, as a bdrdb database was created when 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, select and log in to the bdrdb database on any host's Postgres server.

• 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 process initializes the first node.

• Add the second node.
  • Create the second node. Log in to 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 in to 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, you tell host-one's Postgres instance that it's a PGD node—node-one—and create PGD groups on that node. Then you tell host-two and host-three's Postgres instances that they are PGD nodes—node-two and node-three—and that they must 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 in to host-one's 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. This example creates 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 configure later, to coordinate their operations. In a larger PGD installation, multiple subgroups can exist. These subgroups provide 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 the 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');

Adding the second node

Log in to host-two's 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 node-one's dc1 group. The function takes as a first parameter the connection string of a node already in the group and 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 in to host-three's 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 node-one's dc1 group. The function takes as a first parameter the connection string of a node already in the group and the group name as a second parameter.

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

A PGD cluster is now created.

• On this page
• Creating the PGD cluster
• Worked example
  • Create connection strings for each node
  • Preparing the first node
  • Create the first node
  • Adding the second node
  • Add the third node