Configuring PGD CLI
===================

PGD CLI can be installed on any system that can connect to the PGD
cluster. To use PGD CLI, 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 a EDB
Cloud Service distributed high-availability cluster.

PGD CLI and database connection strings
---------------------------------------

You might not need a database connection string. For example, when
Trusted Postgres Architect installs the PGD CLI on a system, it also
configures the connection to the PGD cluster, which means that the PGD
CLI can connect to the cluster when run.

If you’re installing PGD CLI manually, you must give PGD CLI a database
connection string so it knows which PGD cluster to connect to.

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

.. ::
   If you don't know the database connection strings for your PGD-powered deployment, see  :ref:`Discovering connection strings <Discovering connection strings>`  , which helps you to find the right connection strings for your cluster.

Once you have that information, you can continue.

Configuring the database to connect to
--------------------------------------

PGD CLI takes its database connection information from either the PGD
CLI configuration file or the command line.

Using database connection strings in the command line
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can pass the connection string directly to ``pgd`` using the
``--dsn`` option. For details, see the :ref:`Passing a database connection string <Passing a database connection string>`  . For example:

.. code:: shell

   pgd --dsn "host=kaboom port=5432 user=enterprisedb dbname=pgddb" nodes show --versions

Using database connection strings in an environment variable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As an alternative to passing the connection string on the command line,
you can set the ``PGD_CLI_DSN`` environment variable to the connection
string. For example:

.. code:: shell

   export PGD_CLI_DSN="host=kaboom port=5432 user=enterprisedb dbname=pgddb"
   pgd nodes show --versions

Using a configuration file
^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the ``pgd-cli-config.yml`` configuration file to specify the
database connection string for your cluster. The configuration file must
contain the database connection string for at least one PGD node in the
cluster. The cluster name is optional and isn’t validated.

For example:

.. code:: yaml

   cluster:
     name: cluster-name
     endpoints:
     - "host=host-1 port=5432 dbname=pgddb user=postgres"
     - "host=host-2 port=5432 dbname=pgddb user=postgres"
     - "host=host-3 port=5432 dbname=pgddb user=postgres"

By default, ``pgd-cli-config.yml`` is located in the
``/etc/edb/pgd-cli`` directory. The PGD CLI searches for
``pgd-cli-config.yml`` in the following locations. Precedence order is
high to low.

1. ``/etc/edb/pgd-cli`` (default) 2. ``$HOME/.edb/pgd-cli``

If your configuration file isn’t in either of these directories, you can
use the optional ``-f`` or ``--config-file`` flag on a ``pgd`` command
to set the file to read as configuration. See the :ref:`Passing a database connection string <Passing a database connection string>`  .