Connecting from an application
Applications are supposed to work with the services created by CloudNativePG in the same Kubernetes cluster:
Those services are entirely managed by the Kubernetes cluster and implement a form of Virtual IP as described in the "Service" page of the Kubernetes Documentation.
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.
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.
Please refer to the "Connection Pooling" section 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.
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
DNS is the preferred and recommended discovery method.
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
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
The PostgreSQL operator will generate two
basic-auth type secrets for every
PostgreSQL cluster it deploys:
The secrets contain the username, password, and a working
respectively for the
postgres user and the owner of the database.
-app credentials are the ones that should be used by applications
connecting to the PostgreSQL cluster.
-superuser ones are supposed to be used only for administrative purposes.