Getting Postgres Credentials

How to get the username and password for your application's Postgres database, and connect to it from your machine.

When your PlatformApplication requests a Postgres database through spec.resourceRequirements, the platform creates the database user and password for you. It stores them in a Kubernetes Secret in your application's namespace, and passes them to your app as environment variables.

Developers can't read Secrets, so you get the credentials from an owner of your organization. They read the Secret and share it with you through your team's password manager, such as 1Password. You do this once per database, not every time you connect.

This applies to every Postgres resource type: PostgresCluster, PostgresDatabase, and PostgresFlexibleServer.

1. Collect the details

You need three things for the request. All of them are in your repository's .platform/kubernetes/ folder.

Detail	Where to find it	Example
Environment	The cluster you want to connect to: dev, stg, or prd.	dev
Namespace	Your application's namespace. By default it matches your repository name.	orders-service
Resource name	The resourceName of the database in your PlatformApplication's spec.resourceRequirements.	orders-db

resourceRequirements:
  - resourceType: postgresql
    provider: cnpg
    resourceName: orders-db   # ← the resource name

2. Send the request to an owner

Copy this message, fill in the three details, and send it to an owner of your organization:

Hi! Could you share the Postgres credentials for my application?

  Environment:   dev
  Namespace:     orders-service
  Resource name: orders-db

Please run:

  kubectl get secret orders-db-connection -n orders-service \
    -o go-template='{{range $k, $v := .data}}{{$k}}: {{$v | base64decode}}{{"\n"}}{{end}}'

and save the output (host, port, dbname, username, password) to a
1Password item shared with me. Please don't paste it into Slack, email,
or a ticket.

Docs: https://developer.p6m.dev/docs/platform/application-infrastructure/postgres-credentials

For owners

Whether to share credentials, and for which environments, is your call.

1. Switch to the cluster for the environment in the request.

2. Run the kubectl command in the request. The Secret is named <resource name>-connection, in the application's namespace. The command prints each value on its own line:

   dbname: orders
   host: orders-db-rw
   password: ••••••••
   port: 5432
   username: orders

3. Save all five values in a new item in your password manager, and share it with the developer.

Don't send the values over chat, email, a ticket, or a pull request. They're a live login for the database.

If kubectl returns NotFound, check the resource name and namespace. Then list the connection Secrets in the namespace:

kubectl get secrets -n orders-service | grep -- -connection

3. Connect to the database

How you connect depends on the database type.

PostgresCluster (provider: cnpg)

The database runs inside the cluster, so you reach it through a port-forward. host in the credentials is the in-cluster address <resource name>-rw, which only works from inside the cluster.

1. Switch to the cluster for the environment you asked for. kubectl uses your current context, so on the wrong cluster the next step fails with NotFound, or connects you to the same database in another environment. Check where you are, and switch if needed:

   kubectl config current-context
   kubectl config use-context <context for dev>

2. In one terminal, forward a local port to the database's read-write service:

   kubectl port-forward svc/orders-db-rw 5432:5432 -n orders-service

   If something on your machine already uses port 5432, pick another local port, such as 15432:5432, and use it in the next step.

3. In a second terminal, connect with the dbname, username, and password from your password manager:

   psql "host=localhost port=5432 dbname=orders user=orders"

   psql prompts for the password. Any Postgres client works the same way, with localhost as the host.

PostgresDatabase and PostgresFlexibleServer

These databases run outside the cluster, and host is the server's own address. Whether you can reach it from your machine depends on your organization's network setup. If a direct connection with the stored credentials times out, ask the platform team how to reach that server.

Inside your application

You don't need to fetch credentials for your app. The platform passes them to the first container of your workload as environment variables. By default they're named <RESOURCE_NAME>_<KEY>, in upper case with underscores. For orders-db they are:

• ORDERS_DB_HOST
• ORDERS_DB_PORT
• ORDERS_DB_USERNAME
• ORDERS_DB_PASSWORD
• ORDERS_DB_DBNAME

If the resource sets envPrefix in spec.resourceRequirements, that value replaces <RESOURCE_NAME>. For example, envPrefix: DB gives DB_HOST, DB_PASSWORD, and so on. See envPrefix in the PlatformApplication reference.

Don't add the database to spec.secrets. That field is for secret values you write yourself, such as API keys.

If the credentials stop working

If the stored password is rejected, the database's credentials have changed, for example because the database was created again under a new resource name. Ask an owner to run the command again and update the password manager item.