Step 8 - Using PGD CLI#

Using PGD CLI#

The PGD CLI command uses a configuration file to work out the hosts to connect to. There are Using PGD CLI that allow you to override this to use alternative configuration files or explicitly point at a server. But, by default, PGD CLI looks for a configuration file in preset locations.

The connection to the database is authenticated in the same way as other command line utilities, like the psql command, are authenticated.

Unlike other commands, PGD CLI doesn’t interactively prompt for your password. Therefore, you must pass your password using one of the following methods:

  • Adding an entry to your .pgpass , which includes the host, port, database name, user name, and password - Setting the password in the PGPASSWORD environment variable - Including the password in the connection string

We recommend the first option, as the other options don’t scale well with multiple database clusters, or they compromise password confidentiality.

Configuring and connecting PGD CLI#

  • Ensure PGD CLI is installed. * If PGD CLI was already installed, move to the next step. * For any system, repeat the Step 3 - Configuring PGD repositories step on that system. * Then run the package installation command appropriate for that platform. * RHEL and derivatives: sudo dnf install edb-pgd5-cli * Debian, Ubuntu, and derivatives: sudo apt-get install edb-pgd5-cli

  • Create a configuration file. * This is a YAML file that specifies the cluster and endpoints for PGD CLI to use.

  • Install the configuration file. * Copy the YAML configuration file to a default config directory /etc/edb/pgd-cli/ as pgd-cli-config.yml . * Repeat this process on any system where you want to run PGD CLI.

  • Run pgd-cli.

Use PGD CLI to explore the cluster#

  • Check the health of the cluster with the cluster show --health command.

  • Show the nodes in the cluster with the nodes list command.

  • Show the groups in the cluster with the groups list command.

  • Set a group option with the group set-option command.

  • Switch write leader with the group set-leader command.

For more details about these commands, see the worked example that follows.

Also consult the PGD CLI documentation for details of other configuration options and a full command reference.

Worked example#

Ensure PGD CLI is installed#

In this worked example, you configure and use PGD CLI on host-one, where you’ve already installed Postgres and PGD. You don’t need to install PGD CLI again.

Create a configuration file#

The PGD CLI configuration file is similar to the PGD Proxy configuration file. It’s a YAML file that contains a cluster object. This has two properties:

  • The name of the PGD cluster’s top-level group (as name )

  • An array of endpoints of databases (as endpoints )

cluster:
  name: pgd
  endpoints:
    - host=host-one dbname=bdrdb port=5444
    - host=host-two dbname=bdrdb port=5444
    - host=host-three dbname=bdrdb port=5444

Note that the endpoints in this example specify port=5444 . This is necessary for EDB Postgres Advanced Server instances. For EDB Postgres Extended and community PostgreSQL, you can omit this.

Install the configuration file#

Create the PGD CLI configuration directory:

sudo mkdir -p /etc/edb/pgd-cli

Then, write the configuration to the pgd-cli-config.yml file in the /etc/edb/pgd-cli directory.

For this example, you can run this on host-one to create the file:

cat <<EOF | sudo tee /etc/edb/pgd-cli/pgd-cli-config.yml
cluster:
  name: pgd
  endpoints:
    - host=host-one dbname=bdrdb port=5444
    - host=host-two dbname=bdrdb port=5444
    - host=host-three dbname=bdrdb port=5444
EOF

You can repeat this process on any system where you need to use PGD CLI.

Run PGD CLI#

With the configuration file in place, and logged in as the enterprisedb system user, you can run pgd-cli. For example, you can use the nodes list command to list the nodes in your cluster and their status:

pgd nodes list
__OUTPUT__
Node Name Group Name   Node Kind Join State Node Status
- --------  ----------- --------- ---------- -----------
node-one   dc1         data      ACTIVE     Up
node-three dc1         data      ACTIVE     Up
node-two   dc1         data      ACTIVE     Up

Using PGD CLI to explore the cluster#

Once PGD CLI is configured, you can use it to get PGD-level views of the cluster.

Check the health of the cluster#

The cluster show --health command provides a quick way to view the health of the cluster:

pgd cluster show --health
__OUTPUT__
Check             Status Details
- ---------------- ------ -----------------------------------------------
Connections       Ok     All BDR nodes are accessible
Raft              Ok     Raft Consensus is working correctly
Replication Slots Ok     All PGD replication slots are working correctly
Clock Skew        Ok     Clock drift is within permissible limit
Versions          Ok     All nodes are running the same PGD version

Show the nodes in the cluster#

As previously seen, the pgd groups list command lists the nodes in the cluster:

pgd nodes list
__OUTPUT__
Node Name  Group Name  Node Kind Join State Node Status
- --------- ----------- --------- ---------- -----------
node-one   dc1         data      ACTIVE     Up
node-three dc1         data      ACTIVE     Up
node-two   dc1         data      ACTIVE     Up

This view shows the group the node is a member of and its current status. To find out what versions of PGD and Postgres are running on the nodes, use nodes list --versions :

pgd nodes list --versions
__OUTPUT__
Node Name BDR Version                   Postgres Version
- --------- ---------------------------  --------------------------------
node-one   5.7.0 (snapshot e2534db6d)   16.6 (Debian 16.6-1EDB.bullseye)
node-three 5.7.0 (snapshot e2534db6d)   16.6 (Debian 16.6-1EDB.bullseye)
node-two   5.7.0 (snapshot e2534db6d)   16.6 (Debian 16.6-1EDB.bullseye)

Show the groups in the cluster#

Finally, the pgd groups list command for PGD CLI shows which groups are configured, and more:

pgd groups list
__OUTPUT__
Group Name   Parent Group Name Group Type Nodes
- ----------- ----------------- ---------- -----
pgd                            global     0
dc1          pgd               data       3

This command shows:

  • The groups

  • Their types

  • Their parent group

  • The number of nodes in each group

Set a group option#

You can set group options using PGD CLI, too, using the pgd group set-option command. If you wanted to set the dc1 group’s location to London , you would run:

pgd group dc1 set-option location London
__OUTPUT__
Status Message
- ----- -----------------------------
OK     Command executed successfully

You can verity the new location using the pgd group get-option command:

pgd group dc1 get-option location
__OUTPUT__
Option Name Option Value
- ---------- ------------
location    London

Set the write leader#

If you need to change write leader in a group, to enable maintenance on a host, PGD CLI offers the pgd group set-leader command. You enter a group name after group and the name of the node you want to switch to after set leader :

pgd group dc1 set-leader node-two
__OUTPUT__
Status Message
- ----- -----------------------------
OK     Command executed successfully

You can verify the write leader using the pgd cluster show with the --summary option :

pgd group dc1 show --summary
__OUTPUT__
Group Property    Value
- ---------------- ------------
Group Name        dc1
Parent Group Name pgd
Group Type        data
Write Leader      node-two
Commit Scope

More details on the available commands in PGD CLI are available in the PGD CLI command reference .