FAQ

What is pg-kinetic?

pg-kinetic is a PostgreSQL wire proxy for connection pooling, conservative session handling, read routing, admin inspection, health checks, metrics, and regression tooling.

The proxy keeps clients on the PostgreSQL protocol. Applications connect through pg-kinetic, and pg-kinetic manages backend reuse conservatively so uncertain protocol or session state is pinned, recovered, or discarded instead of being reused unsafely.

Is pg-kinetic installed from a published container image today?

Yes. Use ghcr.io/hookwoods/pg-kinetic:latest for Docker installs and https://helm.pgkinetic.dev for Helm installs.

The local Docker Compose and local chart paths remain useful for development and template changes. See Installation and Quickstart.

Does pg-kinetic implement an HTTP drain endpoint?

No. The HTTP health server currently implements:

Endpoint	Method	Purpose
/healthz	GET	Process liveness
/readyz	GET	Readiness and backend probe state
/state	GET	Non-secret health snapshot

POST /drain and GET /drain are not implemented. Kubernetes manifests should use readiness and liveness probes only.

Are sharding, policy, and mirroring live traffic features?

No. Sharding, policy, and mirroring have domain models and preview or offline commands, but they are not active live-traffic configuration in the main proxy runtime today.

Use:

• Sharding for route-preview behavior
• Policy for policy-preview behavior
• Mirroring for current mirror model status

What configuration format does pg-kinetic use?

pg-kinetic uses TOML configuration. Defaults are created first, an optional config file is parsed next, and non-default CLI or environment values override the file.

Use Configuration as the runtime reference. Important socket fields such as connection.backend_addr require IP:port; hostnames are not accepted there.

What should operators validate before rollout?

Run a focused rollout check before sending application traffic:

1. Validate config with pg-kinetic preflight --config.
2. Verify /healthz, /readyz, and /state.
3. Query admin views such as SHOW POOLS and SHOW CLIENTS.
4. Confirm metrics are reachable when metrics_addr is configured.
5. Test client TLS and authentication settings with the same driver mode used by production applications.
6. Use compatibility or regression checks for driver-sensitive workloads.

Where should agents and crawlers start?

Use the canonical docs root at https://docs.pgkinetic.dev/, the compact agent reference at https://docs.pgkinetic.dev/llms.txt, and the repository at https://github.com/hookwoods/pg-kinetic.