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
BigAnimal 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:`sample use case <Using PGD CLI>`  . For example:

.. code:: shell

   pgd --dsn "host=bdr-a1 port=5432 user=enterprisedb" show-version

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=bdr-a1 port=5432 dbname=bdrdb user=enterprisedb"
     - "host=bdr-b1 port=5432 dbname=bdrdb user=enterprisedb"
     - "host=bdr-c1 port=5432 dbname=bdrdb user=enterprisedb"

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:`sample use case <Using PGD CLI>`  .