Using PGD CLI
=============

What is the PGD CLI?
--------------------

The PGD CLI is a convenient way to connect to and manage your PGD
cluster. To use it, you need a user with PGD superuser privileges or
equivalent. The PGD user with superuser privileges is the :ref:`bdr_superuser role and replication <bdr_superuser role and replication>` 
. An example of an equivalent user is edb_admin on an EDB BigAnimal
distributed high-availability cluster.

..  Important Setting passwords::
   PGD CLI doesn't interactively prompt for your password. 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 databases, or they compromise password confidentiality.

.. ::
   ## Running the PGD CLI

Once you have :ref:`installed pgd-cli <Deploying EDB Postgres Distributed using Trusted Postgres Architect>`  , run the ``pgd`` command to access the PGD
command line interface. The ``pgd`` command needs details about the
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. When you pass the connection string with the ``--dsn``
flag, you don’t need a configuration file. The flag takes precedence
even if a configuration file is present. For example:

.. code:: sh

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

See :ref:`PGD overview <PGD overview>`  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`` uses it. You can override this behavior
using the optional ``-f`` or ``--config-file`` flag. For example:

.. code:: sh

   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:

.. code:: sh

   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.

.. csv-table::
  :header: Setting,Format,Considerations
  :widths: 12,12,25
  :align: left
  :class: longtable

  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 might not be fully supported in future versions.

Accessing the command line help
-------------------------------

To list the supported commands, enter:

.. code:: sh

   pgd help

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

.. code:: sh

   pgd help show-nodes

..  Note 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. !!!