Endpoints

An endpoint is the Postgres process that accepts client connections. Endpoints are ephemeral: they suspend when idle, wake on first packet, and run on the project's separated storage layer. Pay only for the seconds compute is actually running.

Types

Both types attach to exactly one branch. An endpoint cannot move to a different branch; create a new endpoint on the target branch instead.

Suspend on idle

Endpoints suspend after a configurable window of no client activity. The default is 300 seconds (5 minutes). Change it with keon endpoints update <endpoint-id> --suspend-timeout <seconds>: 0 means never suspend; any other value must be 60–3600. Over the API, suspend_after_seconds on POST /v1/branches/{branchId}/endpoints sets it at create time. The new window takes effect on the endpoint's next idle period.

While suspended:

• The compute pod is gone. No CPU, no memory billed.
• Storage is unaffected — your data is durable in the pageserver.
• The endpoint id and connection string remain valid.

Wake

Sending a packet to a suspended endpoint wakes it. A wake that attaches to pre-warmed compute is typically ready in under 2 seconds; the very first wake after a long idle (or after a fresh project) can take 10–30 seconds while the pageserver page cache warms. Standard Postgres drivers do not see this as a timeout in typical configurations — see Troubleshooting if you do.

Routine wakes are fast because the platform keeps a pool of compute pre-warmed ahead of demand: a wake usually attaches to already-running compute rather than booting it from scratch. You don't manage or pay for the pool — it only affects how quickly your endpoint comes back.

State machine

An endpoint transitions through:

Pending → Starting → Running → Stopping → Stopped → (Failed)

• Pending — control plane has accepted the create request and is scheduling the compute pod. If you see an endpoint stuck here for more than a few seconds, see Troubleshooting.
• Starting — the compute pod is up; Postgres is initialising and replaying WAL up to the branch's HEAD.
• Running — accepting client connections.
• Stopping — idle window elapsed; draining connections and flushing local state.
• Stopped — suspended. Waiting for the next packet to wake.
• Failed — terminal error. The endpoint card surfaces the reason; rare, but happens when scheduling fails or the compute image cannot start.

Connection URI

The wire format is documented in Connection strings:

postgresql://<role>:<pwd>@<endpoint_id>.<region>.kisenon.com:5432/<database>?sslmode=require

The hostname is derived from the endpoint id, not the project id — each endpoint terminates TLS independently. TLS is required.

The same endpoint also answers on <endpoint_id>-pooler.<region>.kisenon.com for transaction-pooled connections (on by default) — see Connection strings for the pooled-vs-direct tradeoffs.

Create

Every new branch gets one rw endpoint automatically. To add another:

keon branches add-compute <branch-id>

Optional flags:

• --type ro|rw — defaults to ro (read-only). rw replaces the branch's primary read-write endpoint.
• --min-cu <cu> / --max-cu <cu> — the autoscaling window. --max-cu can only be set here; it is fixed for the endpoint's life.

To change the suspend window afterwards:

keon endpoints update <endpoint-id> --suspend-timeout 600

The CLI returns the endpoint id and the connection string. The endpoint is Running and ready to accept connections within a few seconds of the call returning.

Delete

keon endpoints delete <endpoint-id>

Open client connections are dropped. The endpoint id is retired and its DNS hostname stops resolving. The branch and its data are unaffected.

Related

• Branches — what an endpoint attaches to.
• Connection strings — wire format detail.
• Troubleshooting — stuck states, cold-start timeouts, and friends.