Postgres

Postgres mode intercepts the PostgreSQL wire protocol. For each incoming connection, Waypoint:

Authenticates the caller via Tailscale.
Reads the requested database from the startup message. ✓
Provisions a temporary backend role with the permissions described by the ACL grant. ✓ ✓
Authenticates as that role against the backend (supporting SCRAM, MD5, and cleartext upstream auth) ✓ ✓ ✓ and proxies the rest of the session. ✓

[[listeners]]
name = "pg-main"
listen = ":5432"
mode = "postgres"
backend = "10.0.1.10:5432"
tls_mode = "optional"
use_tailscale_tls = true

[listeners.postgres]
admin_user = "waypoint_admin"
admin_password = "${PG_ADMIN_PASSWORD}"
admin_database = "postgres"
user_prefix = "wp_"
user_ttl = "24h"

Required fields

Field	Purpose
`admin_user` / `admin_password`	Backend credentials Waypoint uses to create roles. Needs `CREATEROLE` plus `CONNECT` on each target database.
`admin_database`	Database to connect to for admin operations (usually `postgres`).
`user_prefix`	All provisioned roles begin with this string. Default `wp_`. ✓ ✓
`user_ttl`	How long a role stays in the database after last use before cleanup eligibility. ✓ ✓

How roles are named

Roles are deterministically named from the caller’s identity and target database, e.g. wp_alice_laptop_appdb. ✓ Names longer than Postgres’s 63-byte identifier limit are deterministically truncated with a hash suffix, so the same caller always resolves to the same role. ✓ This means the same user reconnecting reuses the same role (and its password is rotated each time), keeping the role count bounded.

Per-connection preset override

Postgres clients can request a lower effective preset for one connection via the waypoint_presets query parameter:

postgres://ignored:ignored@waypoint-db/myapp?sslmode=require&waypoint_presets=readonly

Values are readonly, readwrite, or admin. Comma-separated values are accepted; the strongest listed is treated as the maximum. ✓ The override cannot elevate beyond the ACL grant — a readonly grant stays read-only even if the client asks for admin. ✓

When set, Waypoint provisions a scoped backend role for that effective preset and skips raw-SQL grants for that connection. ✓

TLS

Postgres clients negotiate TLS via SSLRequest. Waypoint serves the certificate that matches the requested server name. See TLS for the full certificate-selection logic. Use tls_mode = "require" to reject plaintext clients entirely. ✓

CockroachDB

Waypoint auto-detects CockroachDB backends and adjusts role-lifecycle behavior accordingly. See CockroachDB for the differences.