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 :ref:`Options <Options>`  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 <https://www.postgresql.org/docs/current/libpq-pgpass.html>`_  , 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 :ref:`configure repositories <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 ``check-health`` command.

-  Show the nodes in the cluster with the ``show-nodes`` command.

-  Show the proxies in the cluster with the ``show-proxies`` command.

-  Show the groups in the cluster with the ``show-groups`` command.

-  Set a group option with the ``set-group-options`` command.

-  Switch write leader with the ``switchover`` command.

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

Also consult the :ref:`PGD CLI documentation <../../../cli/>`  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
``show-nodes`` command to list the nodes in your cluster and their
status:

::

   pgd show-nodes
   __OUTPUT__
   Node       Node ID    Group Type Current State Target State Status Seq ID
   - ---       -------    ----- ---- ------------- ------------ ------ ------
   node-one   2824718320 dc1   data ACTIVE        ACTIVE       Up     1
   node-three 1954860017 dc1   data ACTIVE        ACTIVE       Up     3
   node-two   2299992455 dc1   data ACTIVE        ACTIVE       Up     2

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 :ref:`check-health <check-health>`  command provides a quick way to view the health of the
cluster:

::

   pgd check-health
   __OUTPUT__
   Check      Status Message
   - ----      ------ -------
   ClockSkew  Ok     All BDR node pairs have clockskew within permissible limit
   Connection Ok     All BDR nodes are accessible
   Raft       Ok     Raft Consensus is working correctly
   Replslots  Ok     All BDR replication slots are working correctly
   Version    Ok     All nodes are running same BDR versions

Show the nodes in the cluster
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As previously seen, the :ref:`show-nodes <show-nodes>`  command lists the nodes in the
cluster:

::

   pgd show-nodes
   __OUTPUT__
   Node       Node ID    Group Type Current State Target State Status Seq ID
   - ---       -------    ----- ---- ------------- ------------ ------ ------
   node-one   2824718320 dc1   data ACTIVE        ACTIVE       Up     1
   node-three 1954860017 dc1   data ACTIVE        ACTIVE       Up     3
   node-two   2299992455 dc1   data ACTIVE        ACTIVE       Up     2

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 ``show-version`` :

::

   pgd show-version
   __OUTPUT__
   Node       BDR Version Postgres Version
   - ---       ----------- ----------------
   node-one   5.3.0       16.1.0
   node-three 5.3.0       16.1.0
   node-two   5.3.0       16.1.0

Show the proxies in the cluster
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can view the configured proxies, with their groups and ports, using
 :ref:`show-proxies <show-proxies>`  :

::

   pgd show-proxies
   __OUTPUT__
   Proxy           Group Listen Addresses Listen Port
   - ----           ----- ---------------- -----------
   pgd-proxy-one   dc1   [0.0.0.0]        6432
   pgd-proxy-three dc1   [0.0.0.0]        6432
   pgd-proxy-two   dc1   [0.0.0.0]        6432

Show the groups in the cluster
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Finally, the :ref:`show-groups <show-groups>`  command for PGD CLI shows which groups are
configured, and more:

::

   pgd show-node_groups
   __OUTPUT__
   Group Group ID   Type   Parent Group Location Raft Routing Write Leader
   - ---- --------   ----   ------------ -------- ---- ------- ------------
   pgd   1850374637 global                       true false
   dc1   4269540889 data   pgd                   true true    node-one

This command shows:

-  The groups

-  Their types

-  Their parent group

-  The group’s location

-  Whether Raft consensus is enabled

-  Whether the group is routing connections and, if it is, the node
   that’s write leader for that

The location is descriptive metadata, and so far you haven’t set it. You
can use PGD CLI to do that.

Set a group option
^^^^^^^^^^^^^^^^^^

You can set group options using PGD CLI, too, using the :ref:`set-group-options <set-group-options>` 
command. This requires a ``--group-name`` flag to set the group for this
change to affect and an ``--option`` flag with the setting to change. If
you wanted to set the ``dc1`` group’s location to ``London`` , you would
run:

::

   pgd set-group-options --group-name dc1 --option "location=London"
   __OUTPUT__
   group options updated successfully

You can verify that with ``show-groups`` :

::

   pgd show-node_groups
   __OUTPUT__
   Group Group ID   Type   Parent Group Location Raft Routing Write Leader
   - ---- --------   ----   ------------ -------- ---- ------- ------------
   pgd   1850374637 global                       true false
   dc1   4269540889 data   pgd          London   true true    node-one

Switching write leader
^^^^^^^^^^^^^^^^^^^^^^

If you need to change write leader in a group, to enable maintenance on
a host, PGD CLI offers the :ref:`Switchover <Switchover>`  command. It takes a
``--group-name`` flag with the group the node exists in and a
``--node-name`` flag with the name of the node to switch to. You can
then run:

::

   pgd switchover --group-name dc1 --node-name node-two
   __OUTPUT__
   switchover is complete

And you can verify that with ``show-groups`` :

::

   pgd show-groups
   __OUTPUT__
   Group Group ID   Type   Parent Group Location Raft Routing Write Leader
   - ---- --------   ----   ------------ -------- ---- ------- ------------
   pgd   1850374637 global                       true false
   dc1   4269540889 data   pgd          London   true true    node-two

More details on the available commands in PGD CLI are available in the
 :ref:`PGD CLI command reference <../../../cli/command_ref/>`  .