PGD CLI on BigAnimal

Suggest edits

When running a distributed high-availability cluster on BigAnimal, you can use the PGD CLI to manage cluster operations. Examples of these operations include switching over write leaders, performing cluster health checks, and viewing various details about nodes, groups, or other aspects of the cluster.

Installing the PGD CLI

To install the PGD CLI, for Debian and Ubuntu machines, replace <your-token> with your EDB subscription token in the following command:

curl -1sLf 'https://downloads.enterprisedb.com/&lt;your-token&gt;/postgres_distributed/setup.deb.sh' | sudo -E bash
sudo apt-get install edb-pgd5-cli

For RHEL, Rocky, AlmaLinux, or Oracle Linux machines, make the replacement in this command:

curl -1sLf 'https://downloads.enterprisedb.com/&lt;your-token&gt;/postgres_distributed/setup.rpm.sh' | sudo -E bash
sudo yum install edb-pgd5-cli

Connecting to your BigAnimal cluster

Discovering your database connection string

To connect to your distributed high-availability BigAnimal cluster using the PGD CLI, you need to discover the database connection string. From your BigAnimal console:

  1. Log in to the BigAnimal clusters view.
  2. To show only clusters that work with PGD CLI, in the filter, set Cluster Type to Distributed High Availability.
  3. Select your cluster.
  4. In the view of your cluster, select the Connect tab.
  5. Copy the read/write URI from the connection info. This is your connection string.

Using the PGD CLI with your database connection string

Important

PGD doesn't prompt for interactive passwords. Accordingly, you need a .pgpass file properly configured to allow access to the cluster. Your BigAnimal cluster's connection information page has all the information needed for the file.

Without a properly configured .pgpass, you receive a database connection error when using a PGD CLI command, even when using the correct database connection string with the --dsn flag.

To use the PGD CLI with your database connection string, use the --dsn flag with your PGD CLI command:

pgd show-nodes --dsn "<your_connection_string>"

PGD commands in BigAnimal

Note

Three EDB Postgres Distributed CLI commands don't work with distributed high-availability BigAnimal clusters: create-proxy, delete-proxy, and alter-proxy-option. These commands are managed by BigAnimal, as BigAnimal runs on Kubernetes. It's a technical best practice to have the Kubernetes operator handle these functions.

The examples that follow show the most common PGD CLI commands with a BigAnimal cluster.

pgd check-health

pgd check-health provides statuses with relevant messaging regarding the clock skew of node pairs, node accessibility, the current raft leader, replication slot health, and versioning consistency:

$ pgd check-health --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require"
Output
Check      Status  Message                                                    
-----      ------  -------                                                    
ClockSkew  Ok      All BDR node pairs have clockskew within permissible limit 
Connection Ok      All BDR nodes are accessible                               
Raft       Warning There is no RAFT_LEADER, an election might be in progress  
Replslots  Ok      All BDR replication slots are working correctly            
Version    Ok      All nodes are running same BDR versions

pgd show-nodes

pgd show-nodes returns all the nodes in the distributed high-availability cluster and their summaries, including name, node id, group, and current/target state:

$ pgd show-nodes --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require"
Output
Node             Node ID    Group          Type Current State Target State Status Seq ID 
----             -------    -----          ---- ------------- ------------ ------ ------ 
p-mbx2p83u9n-a-1 3537039754 dc1            data ACTIVE        ACTIVE       Up     1      
p-mbx2p83u9n-a-2 3155790619 p-mbx2p83u9n-a data ACTIVE        ACTIVE       Up     2      
p-mbx2p83u9n-a-3 2604177211 p-mbx2p83u9n-a data ACTIVE        ACTIVE       Up     3

pgd show-groups

pgd show-groups returns all groups in your distributed high-availability BigAnimal cluster. It also notes the node that's the current write leader of each group:

$ pgd show-groups --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require"
Output
Group          Group ID   Type   Parent Group   Location Raft  Routing Write Leader     
-----          --------   ----   ------------   -------- ----  ------- ------------     
world          3239291720 global                         true  true    p-mbx2p83u9n-a-1 
dc1            4269540889 data   p-mbx2p83u9n-a          false false                    
p-mbx2p83u9n-a 2800873689 data   world                   true  true    p-mbx2p83u9n-a-3

pgd switchover

pgd switchover manually changes the write leader of the group and can be used to simulate a failover.

$ pgd switchover --group-name world --node-name p-mbx2p83u9n-a-2 --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require"
Output
switchover is complete

See the PGD CLI command reference for the full range of PGD CLI commands and their descriptions.

← Prev

BigAnimal Terraform provider

Next →

Postgres Distributed (PGD) presets on BigAnimal