PgDog

Overview

PgDog is a PostgreSQL connection pooler, load balancer and query router written in Rust. It speaks the PostgreSQL wire protocol on port 6432, so applications change only their connection string: PgDog multiplexes many client connections onto a small pool of real backend connections, sends writes to a primary backend and spreads SELECT queries across replica backends. This template deploys the proxy only — it does not run PostgreSQL. Point it at an existing PostgreSQL or PostgreSQL Highly Available install, or at any external PostgreSQL endpoint. Every credential comes from a secret you create before installing, so no password passes through Helm values.

This template does not create a GVC. It deploys into a GVC you already have, and every resource lands in the GVC you install into. The PostgreSQL backend must already exist and be reachable from that GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-pgdog`	PgDog proxy (standard, stateless, `replicas` copies) serving PostgreSQL clients on port `6432`	—
Secret	`RELEASE_NAME-pgdog-config`	Opaque secret holding the credential-free part of `pgdog.toml`: pool settings and the `databases` backends	—
Secret	`RELEASE_NAME-pgdog-startup`	Opaque secret holding the startup script that builds the final config files from your secrets, then starts PgDog	—
Identity	`RELEASE_NAME-pgdog-identity`	Identity bound to the workload	—
Policy	`RELEASE_NAME-pgdog-policy`	Grants the identity `reveal` on the two secrets above, the admin password secret and every pooled user’s credentials secret	—

How credentials reach PgDog. PgDog reads usernames and passwords only from its config files on disk, and a secret reference cannot be placed inside a file the chart writes. So the chart renders only the credential-free part of pgdog.toml; your secrets are injected into the container as environment variables, and the startup script writes the [admin] table and users.toml from them each time the container starts. The template creates no secret that contains a credential, and uninstalling never deletes yours.

Prerequisites

Both kinds of secret must exist before you install. Secrets are org-level, so no GVC flag is involved. A PostgreSQL backend must also be running, with the role and database your pooled users will connect as.

Create one credentials secret per pooled user

A dictionary secret holding exactly two keys, username and password. PgDog checks client logins against this pair and opens its backend connections with it, so it must be a real PostgreSQL role on the backend:

cpln secret create-dictionary --name USER_CREDENTIALS_SECRET_NAME \
  --entry username=appuser \
  --entry password='YOUR-STRONG-PASSWORD'

If your backend is a PostgreSQL install, you can skip this step and reuse the dictionary secret that template already reads — it holds the same username and password keys, and PgDog ignores its extra database key.Set users[0].credentialsSecretName to this name.

Create the admin password secret

An opaque secret with encoding plain, whose payload is the password for PgDog’s admin database. It is deliberately separate from the pooled-user secrets, so an application that can read its own credentials cannot also reach the admin database:

printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name ADMIN_PASSWORD_SECRET_NAME --encoding plain -f -

Use printf, not echo — echo adds a trailing newline, and the startup script refuses to start with a password that contains one.Set admin.passwordSecretName to this name.

Read a secret back when you need it

The -o yaml is required — a bare cpln secret reveal prints only a summary table:

cpln secret reveal SECRET_NAME -o yaml

Create the secrets before installing. The template refuses to render when a secret name is blank, but a name pointing at a secret that does not exist installs “successfully” and then wedges silently: every resource is reported created, the workload never becomes ready, and cpln logs returns zero lines because no container ever starts. The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-pgdog --gvc GVC_NAME -o yaml

It is get-deployments — plain cpln workload get has no versions key. Once the secret exists the workload recovers on its own after several minutes, or immediately if you force a redeployment:

cpln workload force-redeployment RELEASE_NAME-pgdog --gvc GVC_NAME

Installation

Install with your backend, one pooled user and the admin secret. databases and users are lists, and setting one field of a list entry with --set replaces the whole list, so set every field of each entry:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/pgdog \
  --version 1.1.0 --gvc GVC_NAME \
  --set 'databases[0].name=DATABASE' \
  --set 'databases[0].host=POSTGRES_WORKLOAD_NAME.GVC_NAME.cpln.local' \
  --set 'databases[0].port=5432' \
  --set 'databases[0].role=primary' \
  --set 'users[0].credentialsSecretName=USER_CREDENTIALS_SECRET_NAME' \
  --set 'users[0].database=DATABASE' \
  --set admin.passwordSecretName=ADMIN_PASSWORD_SECRET_NAME

DATABASE must be a real database on the backend, and users[0].database must match a databases[].name. With the PostgreSQL template, POSTGRES_WORKLOAD_NAME is that release’s RELEASE_NAME-postgres workload. To install using another method, follow the instructions for it:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image and Resources

The PgDog image, the CPU and memory reservation (minCpu, minMemory) and limit (maxCpu, maxMemory), and the number of proxy replicas:

image: ghcr.io/pgdogdev/pgdog:v0.1.45

resources:
  minCpu: 100m
  minMemory: 128Mi
  maxCpu: 500m
  maxMemory: 256Mi

replicas: 1

Each replica keeps its own connection pool — see Scaling and Availability before raising replicas.

Backend Databases

Each entry becomes a [[databases]] block in pgdog.toml. Entries that share a name form one cluster: PgDog sends writes to the primary entry and reads to the replica entries.

databases:
  - name: my-pgdog-database  # logical name clients connect to; must be a real database on the backend
    host: my-postgres-workload  # e.g. WORKLOAD_NAME.GVC_NAME.cpln.local for an in-GVC Postgres, or an external hostname
    port: 5432
    role: primary            # options: primary, replica, auto
  # - name: my-pgdog-database
  #   host: my-postgres-replica.GVC_NAME.cpln.local
  #   port: 5432
  #   role: replica

For a backend in the same GVC, always use the fully qualified host WORKLOAD_NAME.GVC_NAME.cpln.local — a bare workload name does not resolve for every workload type.

Backend	`host` for the `primary` entry
PostgreSQL template	`RELEASE_NAME-postgres.GVC_NAME.cpln.local`
PostgreSQL Highly Available template	`RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local` — the HAProxy workload, which always routes to the current leader
External PostgreSQL	Its hostname, with the `port` it listens on

`role`	Behavior
`primary`	Receives write queries (`INSERT`, `UPDATE`, `DELETE`, DDL)
`replica`	Receives `SELECT` queries, spread by `loadBalancing.strategy`
`auto`	PgDog detects whether the backend is a primary or a replica

Pooled Users

Each entry becomes a [[users]] block in users.toml. The username and password come from the dictionary secret named by credentialsSecretName; only the routing target is a value:

users:
  - credentialsSecretName: my-pgdog-user-credentials
    database: my-pgdog-database   # must match a `name` from the databases list above

To pool a second user, create a second dictionary secret (Prerequisites) and add a second entry — one secret per entry, since a secret holds one username and password pair:

users:
  - credentialsSecretName: my-pgdog-user-credentials
    database: my-pgdog-database
  - credentialsSecretName: my-pgdog-reporting-credentials
    database: my-pgdog-database

The chart adds a reveal target to the policy for each secret automatically. Two entries may name the same secret, which routes one role to two databases.

Connection Pooling

pooling:
  mode: transaction          # options: transaction, session, statement
  defaultPoolSize: 10        # max server connections per pool
  minPoolSize: 1             # minimum idle connections kept open
  workers: 2                 # tokio async threads; recommend 2× vCPU count

Mode	Behavior
`transaction`	A backend connection is held only for one transaction, then returned to the pool. Best for most web and API workloads; not compatible with session state such as `SET` variables, temporary tables or advisory locks.
`session`	A backend connection is held for the whole client session. Compatible with every PostgreSQL feature but reuses connections less, so raise `defaultPoolSize` to match concurrent clients.
`statement`	A backend connection is returned to the pool after every statement, so multi-statement transactions are not supported. Accepted by the chart, but not verified with this template; prefer `transaction`.

Timeouts

All values are in milliseconds:

timeouts:
  connect: 5000              # time to establish a backend connection
  checkout: 5000             # max time a client waits for a free connection
  idle: 60000                # idle server connections closed after this
  query: 0                   # per-query timeout; 0 = disabled

Load Balancing

How reads are spread across replica backends. With readWriteSplit: include_primary the primary also serves reads:

loadBalancing:
  strategy: least_active_connections  # options: random, round_robin, least_active_connections
  readWriteSplit: include_primary

Admin Database

PgDog’s built-in admin database for pool statistics and introspection. The database and user names are values; the password comes from the opaque secret you created:

admin:
  database: admin
  user: admin
  passwordSecretName: my-pgdog-admin-password

Authentication and Logging

auth:
  type: scram

logging:
  format: text               # options: text, json, json_flattened
  level: info                # RUST_LOG syntax; e.g. info, debug, pgdog=debug

Access

Internal access controls which workloads may reach the proxy. Public access opens a TCP load balancer on port 6432 to the internet:

publicAccess:
  enabled: false
  # address: my-pgdog-domain.example.com  # name of an existing cpln domain resource

internalAccess:
  type: same-gvc             # options: none, same-gvc, same-org, workload-list
  workloads: []
  # workloads:
  #   - //gvc/my-gvc/workload/my-app

With type: workload-list, list each allowed caller in workloads as //gvc/GVC_NAME/workload/WORKLOAD_NAME. A change to either access setting can take several minutes to take effect; re-test with a real PostgreSQL client before concluding it did not apply.

Connecting

Applications connect exactly as they would to PostgreSQL, on port 6432. The username and password are those in the pooled user’s credentials secret (cpln secret reveal SECRET_NAME -o yaml).

What	Address	Notes
In-GVC clients	`RELEASE_NAME-pgdog.GVC_NAME.cpln.local:6432`	Always use the fully qualified name; the bare `RELEASE_NAME-pgdog` does not resolve
Connection string	`postgresql://USERNAME:PASSWORD@RELEASE_NAME-pgdog.GVC_NAME.cpln.local:6432/DATABASE`	`DATABASE` is a `databases[].name`
Public endpoint	`status.canonicalEndpoint` from `cpln workload get RELEASE_NAME-pgdog --gvc GVC_NAME -o yaml`, port `6432`	Only when `publicAccess.enabled: true`
Admin database	Database `admin.database`, user `admin.user`, same host and port	Password is the payload of the admin password secret

To verify the proxy end to end from your machine — PgDog listening, your credentials accepted and a query answered by the backend — tunnel to it:

cpln port-forward RELEASE_NAME-pgdog 6432:6432 --gvc GVC_NAME

Then, from another terminal:

psql "postgresql://USERNAME:PASSWORD@127.0.0.1:6432/DATABASE" -c 'select version()'

A row with the backend’s PostgreSQL version means the whole path works. Through the same tunnel, connect to the admin database as admin.user and run SHOW POOLS or SHOW CLIENTS to inspect the pools.

Operations

Rotating Credentials

PgDog builds its config files once, when the container starts, so changing a secret has no effect until the workload is redeployed. Because a pooled user’s pair is also PgDog’s backend login, change the role’s password in PostgreSQL first, then update the secret by applying it whole:

cat > rotate.yaml <<'EOF'
kind: secret
name: SECRET_NAME
type: dictionary
data:
  username: USERNAME
  password: NEW-PASSWORD
EOF
cpln apply -f rotate.yaml
cpln secret reveal SECRET_NAME -o yaml

The admin password secret is opaque — apply it the same way with type: opaque and data holding encoding: plain and payload: NEW-VALUE. Then redeploy so PgDog picks up the new values:

cpln workload force-redeployment RELEASE_NAME-pgdog --gvc GVC_NAME

Until the redeployment, PgDog keeps using the old values, with no error and the workload still reported ready.

Upgrading From 1.0.0

Version 1.0.0 took the pooled-user and admin passwords as Helm values, with working defaults published in the public template repository. Version 1.1.0 moves every credential into secrets you create and renames the resource limits:

	1.0.0	1.1.0
Pooled-user name	`users[].name`	`username` key of a dictionary secret you create
Pooled-user password	`users[].password`	`password` key of that same secret
Which secret	—	`users[].credentialsSecretName`, one per entry
Admin password	`admin.password`	`admin.passwordSecretName` — an opaque secret you create
CPU and memory limits	`resources.cpu`, `resources.memory`	`resources.maxCpu`, `resources.maxMemory`

Carrying old values forward stops the upgrade. These conditions are rejected at render time, so the upgrade fails before any resource is touched and the running release is left as it was:

Value you set	Result
`users[].password`	`users[0].password was REMOVED in pgdog 1.1.0. Pooled-user credentials are no longer values` …
`users[].name`	`users[0].name was REMOVED in pgdog 1.1.0. The username now comes from the username key of the dictionary secret` …
`admin.password`	`admin.password was REMOVED in pgdog 1.1.0. The admin password is no longer a value` …
`resources.cpu`	`resources.cpu was RENAMED to resources.maxCpu in pgdog 1.1.0.` …
`resources.memory`	`resources.memory was RENAMED to resources.maxMemory in pgdog 1.1.0.` …
`users[].credentialsSecretName` empty	`users[0].credentialsSecretName is required` …
`admin.passwordSecretName` empty	`admin.passwordSecretName is required` …

To upgrade an existing install:

Create the secrets

Follow Prerequisites. Put the username and password your applications already use into the pooled-user secret so existing connection strings keep working, and choose a new admin password — the 1.0.0 default was published.

Update your values

Remove users[].name, users[].password and admin.password. Set users[].credentialsSecretName and admin.passwordSecretName, and rename resources.cpu and resources.memory to resources.maxCpu and resources.maxMemory if you had overridden them.

Run the upgrade

PgDog holds no data, so there is nothing to migrate; the proxy is replaced and clients reconnect. Pass your full values, including every field of each databases and users entry:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/pgdog \
  --version 1.1.0 --gvc GVC_NAME \
  --set 'databases[0].name=DATABASE' \
  --set 'databases[0].host=POSTGRES_WORKLOAD_NAME.GVC_NAME.cpln.local' \
  --set 'databases[0].port=5432' \
  --set 'databases[0].role=primary' \
  --set 'users[0].credentialsSecretName=USER_CREDENTIALS_SECRET_NAME' \
  --set 'users[0].database=DATABASE' \
  --set admin.passwordSecretName=ADMIN_PASSWORD_SECRET_NAME

Scaling and Availability

PgDog is stateless and holds no data, so a restart or reschedule only drops open client connections; give applications a reconnect policy. The default is one replica, and every upgrade replaces it. To run more proxies, raise replicas. Each replica keeps its own pool, so the backend sees up to replicas × pooling.defaultPoolSize connections per pool — lower defaultPoolSize accordingly and keep the total under the backend’s max_connections. The template ships with a single replica; running several has not been verified.

Troubleshooting

Workload never becomes ready and cpln logs returns nothing

Symptom: the install reports every resource created, the workload stays not ready, and cpln logs prints zero lines.Cause: a secret named by admin.passwordSecretName or a users[].credentialsSecretName does not exist, so the container never starts.Fix: read the deployment message — it is the only place the missing secret is named:

cpln workload get-deployments RELEASE_NAME-pgdog --gvc GVC_NAME -o yaml

Look for

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

under status.versions[].message. Create that secret (Prerequisites); the workload recovers on its own after several minutes, or force a redeployment to skip the wait.

Container exits at start with a FATAL message

Symptom: the workload restarts repeatedly and cpln logs shows a line beginning FATAL:.Cause: a secret exists but a value in it is unusable. FATAL: ... is missing or empty names the secret and key that is empty or absent (a credentials secret needs both username and password). FATAL: ... contains a newline means the value has a trailing newline, usually from creating it with echo.Fix: recreate or re-apply the named secret with the right keys, using printf '%s' rather than echo for an opaque value (Rotating Credentials), then force a redeployment.

Clients get could not translate host name

Symptom: a client fails with could not translate host name "RELEASE_NAME-pgdog" to address.Cause: the bare workload name does not resolve for PgDog’s workload type.Fix: use the fully qualified host RELEASE_NAME-pgdog.GVC_NAME.cpln.local. Apply the same rule to every databases[].host that points at a workload in the GVC.

Logins through PgDog are rejected

Symptom: a client reaches port 6432 but authentication fails, or PgDog cannot open backend connections.Cause: PgDog uses the pooled user’s username and password for the backend connection too, so the pair must be a real role on the backend with access to the target database. A password changed in PostgreSQL but not in the secret — or changed in the secret without a redeployment — produces the same failure.Fix: compare cpln secret reveal SECRET_NAME -o yaml with the role on the backend, make them match, then force a redeployment.

Install or upgrade fails at render

Symptom: cpln helm install or cpln helm upgrade exits before touching any resource with a message such as users[0].database is "...", which is not a name in .Values.databases or At least one entry is required in .Values.databases.Cause: a users[].database does not match any databases[].name, or a list was replaced by a partial --set (setting one field of a list entry drops the others), or a 1.0.0 key is still set (Upgrading From 1.0.0).Fix: pass every field of each databases and users entry, make each users[].database match a databases[].name, and remove the old keys.

Important Notes

Create every pooled-user credentials secret and the admin password secret before you install; a missing one wedges the workload with no log output.
PgDog is a proxy only — the PostgreSQL backend, its roles and its databases must already exist.
Clients connect on port 6432, not 5432, using the fully qualified RELEASE_NAME-pgdog.GVC_NAME.cpln.local.
Each pooled user’s credentials are also PgDog’s backend login, so they must match a real PostgreSQL role.
A changed secret takes effect only after cpln workload force-redeployment.
In transaction mode, session state (SET variables, temporary tables, advisory locks) is not kept between transactions; use session if your application depends on it.
On 1.0.0, treat the published default passwords as compromised and choose new ones when you upgrade.

External References

PgDog Documentation

Official PgDog documentation

pgdog.toml Reference

Pool, timeout, load-balancing and database settings

users.toml Reference

How PgDog maps pooled users onto backend databases

PgDog GitHub

Source code and issue tracker

PgDog Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image and Resources

Backend Databases

Pooled Users

Connection Pooling

Timeouts

Load Balancing

Admin Database

Authentication and Logging

Access

Connecting

Operations

Rotating Credentials

Upgrading From 1.0.0

Scaling and Availability

Troubleshooting

Important Notes

External References

PgDog Documentation

pgdog.toml Reference

users.toml Reference

PgDog GitHub

PgDog Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Resources

​Backend Databases

​Pooled Users

​Connection Pooling

​Timeouts

​Load Balancing

​Admin Database

​Authentication and Logging

​Access

​Connecting

​Operations

​Rotating Credentials

​Upgrading From 1.0.0

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

PgDog Documentation

pgdog.toml Reference

users.toml Reference

PgDog GitHub

PgDog Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image and Resources

Backend Databases

Pooled Users

Connection Pooling

Timeouts

Load Balancing

Admin Database

Authentication and Logging

Access

Connecting

Operations

Rotating Credentials

Upgrading From 1.0.0

Scaling and Availability

Troubleshooting

Important Notes

External References