Connections

Direct access

Use the direct URL when you need a normal PostgreSQL session: administrative SQL, psql, and migration tools that expect session-level features (advisory locks, LISTEN/NOTIFY, prepared statements with named cursors, DDL in transactions).

Pooled access

Use the pooled URL for app traffic with many short-lived connections. The infrastructure layer runs managed connection pooling (transaction pooling), so your app can stay busy without exhausting the plan's connection budget. Avoid session-level state on pooled connections — the full list of what breaks and the per-driver flags are in Connection pooling.

Which URL goes where

Connection fields

• Host and ports come from the project's region
• Each project has a generated database name and role name
• The dashboard exposes both URLs once the provision job completes; the CLI writes them as DATABASE_URL (pooled), DATABASE_DIRECT_URL, and DATABASE_POOL_URL
• Integrations (Vercel, Netlify, GitHub Action) use the names DATABASE_URL (pooled) and DATABASE_URL_UNPOOLED (direct)
• Preview databases expose the same direct and pooled connection pattern

TLS

Connections require TLS. Keep sslmode=require (or stricter) in the URL — it is included in the URLs CapyDB hands out. If a client errors with "SSL off" or refuses to negotiate TLS, check that the parameter was not stripped when the URL was copied around.

Credential rotation

Rotating credentials (dashboard, POST /v1/projects/{id}/credentials/rotate) generates a new password and invalidates the old URLs. Connected Vercel and Netlify integrations re-push env vars automatically; anything else holding the old URL needs a manual update. A credentials.rotated webhook event fires when it completes. Invalidation timing and the full runbook are in Credential rotation.