Join method

When scaling up a PGD group by adding more data nodes or creating cross-region groups, it’s crucial for new nodes to join the existing group properly. There are two methods for joining:

• Logical join

This method uses the bdr.join_node_group function to integrate the new node into the PGD group. It’s important that the joining node doesn’t contain any schemas or data present in the PGD group. We recommend that the new database contain only the BDR extension, as data synchronization occurs during the join.

• Physical join

This method uses the bdr_init_physical command to speed up the joining process. You can prepare data in advance before executing bdr_init_physical .

For more information about join methods, see Creating and joining PGD groups .

The initial group

The PGD4K operator allows you to configure the join methods for nodes joining PGD groups as well as for groups joining other groups.

When creating a single PGD group, you must configure it to create the parent group (spec.pgd.parentGroup.create =true). If you intend to create multiple PGD groups that will cross join, at least one of these groups must be designated to form the parent group. This group is referred to as the initial PGD group.

The first node in the initial PGD group can either be restored from a backup (as described in the recovery documentation) or created from scratch. This node will always use a logical join to connect to the parent group it created. Conversely, the first node in the non-initial PGD group is used for cross joining with other PGD groups.

You can configure the join method for the first node (group join) and the subsequent nodes (node join) separately.

Note

In the scenario where a group joins another group, the first node of the joining group actually creates the group first before joining a different group (either physically or logically).

Configure the join method for node join

You can configure the join method for a node joining a group when scaling up the PGD group and adding new nodes to the local group. In this context, the joining group is the same as the node group.

node join local group

The spec.cnp.joinMethod parameter configures how a node joins a local group. By default, a logical join is used. To enable a physical join for a new node, set spec.cnp.joinMethod =physical .

In the following example, the second node uses the pg_basebackup command to replicate data from the first node in the region-a group. Then it uses bdr_init_physical to join the region-a group.

This example shows a physical join:

apiVersion: pgd.k8s.enterprisedb.io/v1beta1
kind: PGDGroup
metadata:
  name: region-a
spec:
  instances: 2
  proxyInstances: 2
  witnessInstances: 1
  cnp:
    joinMethod: physical
    storage:
      size: 1Gi
  ...

Configure the join method for group join

You can configure the join method for group joins when creating cross-region PGD groups. The first node in the new PGD group joins an existing PGD group. In this context, the joining group is distinct from the node group.

node join remote group

The PGD4K operator uses the spec.pgd.joinMethod section (which defaults to logical) to determine how PGD groups join with each other. It uses the spec.pgd.discovery section to specify the target to join.

This example shows a logical join, where spec.pgd.groupJoinMethod=logical . The first node in the region-b group waits for all hosts specified in spec.pgd.discovery to become available. It then identifies a suitable target to perform the logical join using the bdr.join_node_group function. The group service of all remote groups is typically defined in the discovery section for this type of join.

apiVersion: pgd.k8s.enterprisedb.io/v1beta1
kind: PGDGroup
metadata:
  name: region-b
  namespace: region-b
spec:
  instances: 2
  proxyInstances: 2
  witnessInstances: 1
  pgd:
    parentGroup:
      name: world
    groupJoinMethod: logical
    discovery:
      - host: region-a-group
      - host: region-c-group
  cnp:
    storage:
      size: 1Gi

This example shows a physical join, configured with spec.pgd.groupJoinMethod=physical . The first node in the region-b group will traverse all the nodes defined in spec.pgd.discovery , waiting to find one node with a successful Raft consensus to perform the physical join using bdr_init_physical . Typically, the node service of the remote group is specified in the discovery section for this type of join.

apiVersion: pgd.k8s.enterprisedb.io/v1beta1
kind: PGDGroup
metadata:
  name: region-b
spec:
  instances: 2
  proxyInstances: 2
  witnessInstances: 1
  pgd:
    parentGroup:
      name: world
    groupJoinMethod: physical
    discovery:
      - host: region-a-3-node
      - host: region-a-1-node
      - host: region-a-2-node
  cnp:
    joinMethod: physical
    storage:
      size: 1Gi

Note

A group join is essentially a type of node join, specifically when the first node in the group joins a node from a different group.

Note

Witness nodes always use a logical join to connect to a group.