Skip to main content

pg-kinetic v1.0.0-rc.1

This release candidate rehearses the stable 1.0 contract. It covers connection pooling, PostgreSQL wire compatibility, TLS and authentication, bounded backpressure, conservative read routing, and single-primary recovery. The default runtime is thread_per_core; tokio_default remains selectable at runtime, and Linux builds compiled with the io-uring cargo feature can select the stable io_uring runtime.

Release checklist​

  • Run bash scripts/release/assert-rc-notes.sh.
  • Run bash scripts/release/assert-contract.sh.
  • Run bash scripts/release/run-stable-gates.sh on Linux with Docker.
  • Run the deployment rehearsal below and retain only redacted CI evidence.
  • Verify the image digest and Helm chart package before promotion.
  • Confirm the required compatibility suites pass for direct PostgreSQL and pg-kinetic.
  • Confirm no preview-only surface is part of the production rollout.

Compatibility evidence​

The release claim requires a reproducible Linux Docker run. Execute:

bash scripts/release/run-stable-gates.sh
docker compose -f deploy/docker-compose.yml up --detach --build
curl -fsS http://127.0.0.1:9091/readyz
docker compose -f deploy/docker-compose.yml down

The stable gate records its redacted summary under the ignored target/release-evidence/ directory. Local macOS runs are directional only and must not be used as release performance evidence. A failed gate blocks the RC.

Rollout​

Use the immutable image tag ghcr.io/hookwoods/pg-kinetic:1.0.0-rc.1 and Helm chart version 1.0.0-rc.1. Resolve and record the image digest before rollout:

docker pull ghcr.io/hookwoods/pg-kinetic:1.0.0-rc.1
docker inspect --format '{{index .RepoDigests 0}}' ghcr.io/hookwoods/pg-kinetic:1.0.0-rc.1
helm repo update
helm upgrade --install pg-kinetic pgkinetic/pg-kinetic \
  --version 1.0.0-rc.1 \
  --set image.repository=ghcr.io/hookwoods/pg-kinetic \
  --set image.tag=1.0.0-rc.1 \
  --wait --timeout 5m

The chart must expose readiness and liveness probes for /readyz and /healthz on port 9091. Keep the existing PostgreSQL endpoint available. Start with a 1% canary, then increase only after each observation window is clean. The configured drain timeout is 45 seconds; allow at least 65 seconds for Kubernetes termination grace so draining completes before SIGKILL.

For the canary, abort and roll back if any of these thresholds are met for two consecutive five-minute windows, or immediately for a critical authentication or data-integrity error:

  • session establishment or checkout errors exceed 1% of attempts or rise by 0.5 percentage points over the direct-PostgreSQL baseline;
  • PostgreSQL connection errors or unexpected SQLSTATEs exceed 0.1% of requests, or any write is retried after response bytes were sent;
  • p95 query latency is more than 25% above baseline and exceeds 250 ms, or checkout wait p95 exceeds 100 ms without a documented capacity cause;
  • /readyz returns 503 for more than two consecutive probes or backend recovery/discard outcomes spike without an approved failure test.

Rollback trigger​

Rollback when any threshold above is met, a required driver smoke test fails, TLS or authentication behavior changes unexpectedly, session state is unsafe, or the single-primary recovery contract is not observed. Stop increasing the canary, remove pg-kinetic from service traffic, and preserve redacted metrics, logs, SQLSTATEs, and admin snapshots.

Restore direct PostgreSQL by selecting the original Service or reverting the application connection string:

kubectl -n <namespace> patch deployment/<app> --type merge \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"<container>","env":[{"name":"DATABASE_URL","value":"postgres://[email protected]:5432/app_db"}]}]}}}}'

For a rollback that keeps the proxy path, restore the previously validated immutable image tag and chart version:

helm upgrade --install pg-kinetic pgkinetic/pg-kinetic \
  --version <previous-chart-version> \
  --set image.repository=ghcr.io/hookwoods/pg-kinetic \
  --set image.tag=<previous-image-tag> \
  --wait --timeout 5m

Verify /readyz, run the application smoke query, and keep direct PostgreSQL available until the rollback is confirmed.

Known exclusions​

Sharding, policy enforcement, live traffic mirroring, and adaptive automation are preview-only. They are not supported for live traffic in 1.0 and are not part of this RC acceptance. This release makes no PgBouncer, PgDog, RDS Proxy, or Hyperdrive feature-parity claim. Automatic promotion, multi-primary operation, global edge pooling, and caching are also outside the stable scope.