> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codezero.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Listeners

> Configure PostgreSQL listener ports and database credential injection.

For database connections, cordon can inject credentials at the wire protocol level. PostgreSQL listeners are configured as `[[listeners]]` entries, separate from HTTP [routes](https://docs.codezero.io/configuration/routes.md), with `port` for the local listener and `upstream` for the real database host and port.

Prefer [`cordon listener add`](https://docs.codezero.io/cli/listener#cordon-listener-add) and [`cordon listener edit`](https://docs.codezero.io/cli/listener#cordon-listener-edit) over hand-editing listener entries in `cordon.toml`. The CLI validates listener names, ports, TLS mode, and secret-source fields, and is meant as the safer way to produce this configuration. `upstream` is taken as-is and not format-checked at `add`/`edit` time — a malformed address (e.g. missing port) is only caught when `cordon start` tries to parse it. The TOML below is the reference format when you need to inspect, review, or automate outside the CLI.

## Listener structure

```toml theme={null}
[[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. Route and listener names share one namespace and must be unique. |
| `port` | integer | Yes | Local port to listen on. |
| `upstream` | string | Yes | Upstream database host and port, such as `db.example.com:5432`. |
| `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](https://docs.codezero.io/configuration/secret-sources.md). |

Connect your application to `localhost:15432` instead of the upstream database. Cordon injects the password during the PostgreSQL authentication handshake.

Listener ports must be unique and cannot equal the HTTP proxy `listen` port.

## TLS behavior

`client_tls = "accept"` accepts PostgreSQL SSL requests when valid `tls.ca_cert_path` and `tls.ca_key_path` are configured, while still allowing plaintext clients. `client_tls = "require"` rejects plaintext startup packets and requires those CA paths. `client_tls = "disable"` declines SSL requests and keeps plaintext-only behavior. Omitted `client_tls` behaves as `accept`.

PostgreSQL client TLS uses the configured Cordon CA. Clients using `sslmode=verify-ca` or `sslmode=verify-full` must trust that CA. Cordon presents a loopback certificate 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.

## Upstream policy

PostgreSQL listener upstreams are configured trust decisions in v1, matching configured HTTP credential routes. Cordon resolves the upstream through the central resolver and connects to the selected `SocketAddr`, so DNS is pinned before the listener starts forwarding connections. Private, loopback, and link-local upstream policy will be revisited post-v1 in [#531](https://github.com/codezero-io/cordon/issues/531).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.