Connecting from an application
==============================

Applications are supposed to work with the services created by EDB
CloudNativePG Cluster in the same Kubernetes cluster.

For more information on services and how to manage them, please refer to
the :ref:`Service Management <Service Management>`  section.

..  Hint::
   It is highly recommended using those services in your applications, and avoiding connecting directly to a specific PostgreSQL instance, as the latter can change during the cluster lifetime.

You can use these services in your applications through:

- DNS resolution

- environment variables

For the credentials to connect to PostgreSQL, you can use the secrets
generated by the operator.

..  Seealso::
   Please refer to the  :ref:`Connection pooling with PgBouncer <Connection pooling with PgBouncer>`  for information about how to take advantage of PgBouncer as a connection pooler, and create an access layer between your applications and the PostgreSQL clusters.

DNS resolution
^^^^^^^^^^^^^^

You can use the Kubernetes DNS service to point to a given server. The
Kubernetes DNS service is required by the operator. You can do that by
using the name of the service if the application is deployed in the same
namespace as the PostgreSQL cluster. In case the PostgreSQL cluster
resides in a different namespace, you can use the full qualifier:
``service-name.namespace-name`` .

DNS is the preferred and recommended discovery method.

Environment variables
^^^^^^^^^^^^^^^^^^^^^

If you deploy your application in the same namespace that contains the
PostgreSQL cluster, you can also use environment variables to connect to
the database.

For example, suppose that your PostgreSQL cluster is called
``pg-database`` , you can use the following environment variables in
your applications:

- ``PG_DATABASE_R_SERVICE_HOST`` : the IP address of the service
  pointing to all the PostgreSQL instances for read-only workloads

- ``PG_DATABASE_RO_SERVICE_HOST`` : the IP address of the service
  pointing to all hot-standby replicas of the cluster

- ``PG_DATABASE_RW_SERVICE_HOST`` : the IP address of the service
  pointing to the *primary* instance of the cluster

Secrets
^^^^^^^

The PostgreSQL operator will generate up to two ``basic-auth`` type
secrets for every PostgreSQL cluster it deploys:

- ``[cluster name]-app`` (unless you have provided an existing secret
  through ``.spec.bootstrap.initdb.secret.name`` )

- ``[cluster name]-superuser`` (if ``.spec.enableSuperuserAccess`` is
  set to ``true`` and you have not specified a different secret using
  ``.spec.superuserSecret`` )

Each secret contain the following:

- username

- password

- hostname to the RW service

- port number

- database name

- a working `.pgpass file <https://www.postgresql.org/docs/current/libpq-pgpass.html>`_ 

- ::

     `uri <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_  

- ::

     `jdbc-uri <https://jdbc.postgresql.org/documentation/use/#connecting-to-the-database>`_  

The ``-app`` credentials are the ones that should be used by
applications connecting to the PostgreSQL cluster, and correspond to the
user *owning* the database.

The ``-superuser`` ones are supposed to be used only for administrative
purposes, and correspond to the ``postgres`` user.

..  Important::
   Superuser access over the network is disabled by default.