Using PGD CLI v5

What is the PGD CLI

The PGD CLI is a convenient way to connect to and manage your PGD cluster. You will need the credentials of a Postgres users with PGD superuser privileges - the bdr_superuser role - or equivalent (e.g. edb_admin on BigAnimal distributed high availability) to use it.

Setting passwords

PGD CLI does not interactively prompt for your user's password. You must pass your password using one of the following methods:

Adding an entry to your .pgpass password file 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 databases or compromise password confidentiality.

Running the PGD CLI

Once you have installed pgd-cli, run the pgd command to access the PGD command line interface. The pgd command will need details of which host, port, and database to connect to, along with your username and password.

Passing a database connection string

Use the --dsn flag to pass a database connection string to the pgd command. You don't need a configuration file when you pass the connection string with the --dsn flag. The flag takes precedence even if a configuration file is present. For example:

pgd show-nodes --dsn "host=bdr-a1 port=5432 dbname=bdrdb user=enterprisedb"

See pgd in the command reference for a description of the command options.

Specifying a configuration file

If a pgd-cli-config.yml file is in /etc/edb/pgd-cli or $HOME/.edb/pgd-cli, pgd will automatically use it. You can override this behavior using the optional -f or --config-file flag. For example:

pgd show-nodes -f /opt/my-config.yml
Node             Node ID    Group          Type    Current State Target State Status Seq ID
----             -------    -----          ----    ------------- ------------ ------ ------
p-vjljj303dk-a-1 2573417965 p-vjljj303dk-a data    ACTIVE        ACTIVE       Up     1
p-vjljj303dk-a-2 126163807  p-vjljj303dk-a data    ACTIVE        ACTIVE       Up     2
p-vjljj303dk-a-3 3521351376 p-vjljj303dk-a witness ACTIVE        ACTIVE       Up     3

Specifying the output format

Use the -o or --output flag to change the default output format to JSON or YAML. For example:

pgd show-nodes -o json
[
	{
		"node_id": 2573417965,
		"node_name": "p-vjljj303dk-a-1",
		"node_group_id": 4169125197,
		"node_group_name": "p-vjljj303dk-a",
		"node_kind_name": "data",
		"current_state": "ACTIVE",
		"target_state": "ACTIVE",
		"status": "Up",
		"node_seq_id": 1,
		"node_local_dbname": "bdrdb",
		"interface_connstr": "host=p-vjljj303dk-a-1-node.vmk31wilqpjeopka.biganimal.io user=streaming_replica sslmode=verify-full port=5432 sslkey=/controller/certificates/streaming_replica.key sslcert=/controller/certificates/streaming_replica.crt sslrootcert=/controller/certificates/server-ca.crt application_name=p-vjljj303dk-a-1 dbname=bdrdb",
		"route_priority": -1,
		"route_fence": false,
		"route_writes": true,
		"route_reads": true,
		"route_dsn": "host=p-vjljj303dk-a-1-node.vmk31wilqpjeopka.biganimal.io user=streaming_replica sslmode=verify-full port=5432 sslkey=/controller/certificates/streaming_replica.key sslcert=/controller/certificates/streaming_replica.crt sslrootcert=/controller/certificates/server-ca.crt application_name=p-vjljj303dk-a-1 dbname=bdrdb"
	},
...
]

The PGD CLI supports the following output formats:

Setting	Format	Considerations
none	Tabular	Default format. This setting presents the data in tabular form.
`json`	JSON	Presents the raw data with no formatting. For some commands, the JSON output might show more data than the tabular output, such as extra fields and more detailed messages.
`yaml`	YAML	Similar to the JSON output, but as YAML and with the fields ordered alphabetically. Experimental and may not be fully supported in future versions.

Accessing the command line help

To list the supported commands, enter:

pgd help

For help with a specific command and its parameters, enter pgd help <command_name>. For example:

pgd help show-nodes

Avoiding stale data

The PGD CLI can return stale data on the state of the cluster if it's still connecting to nodes previously parted from the cluster. Edit the pgd-cli-config.yml file, or change your --dsn settings to ensure you are connecting to active nodes in the cluster.

← Prev

Installing PGD CLI

Configuring PGD CLI