Add a database to your application

Create a PostgreSQL database and connect it to an application in your dev cluster. You need tenant admin access and the Kupe CLI.

1. Create the database

kupe database create orders-db --cpu 250m --memory 512Mi --storage 5Gi

The command waits for Running. You can also use Databases → Create Database in the console and choose the Dev preset. Leave deletion protection on.

2. Give your application access

kupe database binding add orders-db --cluster dev --namespace orders-api --role readwrite

Wait for Ready. The binding creates the namespace if needed, a Service named orders-db, and a credentials Secret named orders-db-readwrite.

kubectl get service orders-db -n orders-api
kubectl get secret orders-db-readwrite -n orders-api

The readwrite role reads and writes rows. Schema migrations need a separate owner binding; keep it in a different namespace:

kupe database binding add orders-db --cluster dev --namespace orders-migrate --role owner

Run migrations there using orders-db-owner. The database name inside PostgreSQL is orders_db. Use readonly for applications that only read data.

3. Connect your application

Mount the binding Secret in your Deployment:

spec:
  template:
    spec:
      containers:
        - name: api
          env:
            - name: SERVICE_BINDING_ROOT
              value: /bindings
          volumeMounts:
            - name: database
              mountPath: /bindings/orders-db-readwrite
              readOnly: true
      volumes:
        - name: database
          secret:
            secretName: orders-db-readwrite

Read the uri file for the connection string. It expects the Secret at /bindings/orders-db-readwrite and uses the supplied ca.crt. Keep sslmode=verify-full. If you use a different mount path, build the connection from the Secret’s individual fields instead.

Mounted files receive updated credentials after rotation. Restart applications that only read credentials at startup. Only namespaces with a binding can connect.

The database sample shows a complete application and migration setup. For Terraform, use the database guide.

Clean up

Disable deletion protection before deleting:

kupe database update orders-db --deletion-protection=false
kupe database delete orders-db

This removes the database and its bindings. Delete the application namespaces separately if you no longer need them. Deleted database storage is retained for 7 days for support-assisted recovery, then permanently deleted.

See Databases or contact support for help with resizing, credentials, or connection problems.