Database Connections

Cordon can inject credentials into database connections, not just HTTP APIs. For PostgreSQL, cordon intercepts the wire protocol handshake and injects the password before the connection reaches the upstream database. Your application connects to a local port with no password and cordon handles authentication transparently.

How it works

Cordon listens on a local port (e.g., 15432)
Your app connects to localhost:15432 with no password
Cordon intercepts the PostgreSQL authentication handshake
The real password, resolved when Cordon starts, is injected into the authentication handshake
The authenticated connection is forwarded to the upstream database

Your application never sees or handles database credentials.

PostgreSQL listeners currently resolve credentials at startup, not per connection. If you rotate the underlying secret, restart Cordon to pick up the new value.

Configuration

Database connections are configured as [[listeners]] entries in cordon.toml, alongside HTTP routes. See Listeners for the full configuration reference.

listen = 6790

[tls]
enabled = true
# Substitute paths from your real `cordon.toml` (typically under ~/.config/cordon/projects/<namespace>/certs/).
ca_cert_path = "/path/to/ca-cert.pem"
ca_key_path = "/path/to/ca-key.pem"

# ... your HTTP routes ...

[[listeners]]
name = "prod-db"
port = 15432
upstream = "db.prod.example.com:5432"
client_tls = "accept"

[listeners.auth]
type = "password"
username = "app_user"

[listeners.auth.secret]
source = "1password"
account = "my-team"
vault = "Engineering"
item = "Postgres Prod"
field = "password"

Field	Type	Required	Description
`name`	string	Yes	Identifier for the listener (used in logs)
`port`	integer	Yes	Local port to listen on
`upstream`	string	Yes	Upstream database host and port
`client_tls`	string	No	Client-to-Cordon TLS mode: `accept` (default), `require`, or `disable`.
`auth.type`	string	Yes	Auth type. Currently `password`.
`auth.username`	string	Yes	Username to authenticate as
`auth.secret`	object	Yes	Secret source reference. See Secret Sources.

PostgreSQL listener upstreams are configured trust decisions in v1, matching configured HTTP credential routes. Cordon resolves the configured upstream once at listener startup and connects to the selected SocketAddr, which pins DNS and avoids a second lookup before connecting. Private, loopback, and link-local upstream policy will be revisited post-v1 in #531.

Client TLS

PostgreSQL clients can request TLS from the local Cordon listener by sending a PostgreSQL SSLRequest before the startup packet. Configure client_tls on each listener:

Mode	Behavior
`accept`	Default. Accepts TLS when Cordon can load valid `tls.ca_cert_path` and `tls.ca_key_path`; plaintext clients still work. If no usable CA is configured, Cordon declines SSL requests to preserve `sslmode=prefer` and plaintext behavior.
`require`	Requires clients to request and complete TLS before the PostgreSQL startup packet. This mode requires `tls.ca_cert_path` and `tls.ca_key_path`.
`disable`	Declines PostgreSQL SSL requests and continues only with clients that fall back to plaintext.

Cordon uses the same local CA configured under [tls] for PostgreSQL client TLS. Clients using sslmode=verify-ca or sslmode=verify-full must trust that CA, for example by running cordon trust or by configuring the client trust store directly. Cordon presents a loopback certificate valid for localhost, 127.0.0.1, and ::1. For sslmode=verify-full, connect to the local listener with one of those host identities.

Cordon always requires TLS on the Cordon-to-upstream PostgreSQL leg. It sends a PostgreSQL SSLRequest to the upstream server and completes TLS before sending startup or authentication data. If the upstream declines TLS or certificate verification fails, Cordon fails closed and does not send credentials.

Connecting your application

Point your application at the local port instead of the upstream database:

Connection string
Environment variable

postgresql://app_user@localhost:15432/mydb

No password in the connection string. Cordon injects it.

DATABASE_URL=postgresql://app_user@localhost:15432/mydb

Multiple databases

Configure multiple PostgreSQL listeners for different databases, each on its own local port:

[[listeners]]
name = "prod-db"
port = 15432
upstream = "db.prod.example.com:5432"
client_tls = "accept"

[listeners.auth]
type = "password"
username = "app_user"

[listeners.auth.secret]
source = "1password"
account = "my-team"
vault = "Engineering"
item = "Postgres Prod"
field = "password"

[[listeners]]
name = "staging-db"
port = 15433
upstream = "db.staging.example.com:5432"
client_tls = "accept"

[listeners.auth]
type = "password"
username = "staging_user"

[listeners.auth.secret]
source = "keyring"
account = "staging-pg-pass"

Getting Started

Configuration

Guides

CLI Reference

Security

Database Connections

How it works

Configuration

Client TLS

Connecting your application

Multiple databases

​How it works

​Configuration

​Client TLS

​Connecting your application

​Multiple databases

How it works

Configuration

Client TLS

Connecting your application

Multiple databases