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 <installing>`  , 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:`Cleanup of PGD metadata <Cleanup of PGD metadata>`  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.