Connecting from an application

Applications are supposed to work with the services created by CloudNativePG in the same Kubernetes cluster:

  • [cluster name]-rw

  • [cluster name]-ro

  • [cluster name]-r

Those services are entirely managed by the Kubernetes cluster and implement a form of Virtual IP as described in the The `microservice type<The microservice type>` .

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.

Warning

The operator will create another service, named [cluster name]-any . That service is used internally to manage PostgreSQL instance discovery. It’s not supposed to be used directly by applications.

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 two basic-auth type secrets for every PostgreSQL cluster it deploys:

  • [cluster name]-superuser

  • [cluster name]-app

The secrets contain the username, password, and a working .pgpass file respectively for the postgres user and the owner of the database.

The -app credentials are the ones that should be used by applications connecting to the PostgreSQL cluster.

The -superuser ones are supposed to be used only for administrative purposes.