Provision a logical database on platform CNPG

Канон: wilix-site/content/one/docs/runbooks/cnpg-provision-db.md (этот файл).

Create a new PostgreSQL role + database on the shared platform cluster ({{ release }}-pg). Use this for migrations like ContextForge and Daytona — not for the bootstrap wilix_one DB (created by CNPG initdb).

Prerequisites

• kubectl access to the platform namespace
• Helm/werf deploy rights for postgres.cnpg.enableSuperuserAccess
• Generated app password (no single quotes — the provision script rejects them)

Production defaults:

Item	Value
Namespace	platform release namespace (e.g. wilix-one-platform)
Cluster	wilix-one-platform-production-pg
RW Service	wilix-one-platform-production-pg-rw:5432
Superuser Secret	wilix-one-platform-production-pg-superuser (only while enabled)

Checklist (secret mode — preferred)

1. Enable superuser access — set in .helm/values-production.yaml:

   postgres:
     cnpg:
       enableSuperuserAccess: true
   

   Deploy (werf/helm upgrade).

2. Wait for superuser Secret — CNPG creates <cluster>-superuser when access is enabled:

   NS=wilix-one-platform
   CLUSTER=wilix-one-platform-production-pg
   kubectl -n "$NS" wait --for=jsonpath='{.data.password}'= --timeout=120s \
     secret/${CLUSTER}-superuser
   

3. Run provision script — from repo root:

   APP_PASS=$(openssl rand -base64 24)
   export APP_PASS
   
   ./scripts/cnpg-provision-db.sh \
     --namespace "$NS" \
     --cluster "$CLUSTER" \
     --db contextforge \
     --role contextforge \
     --password-from-env APP_PASS \
     --mode secret
   

   Idempotent: re-run updates the role password and skips CREATE DATABASE if it exists.

4. Disable superuser access — set postgres.cnpg.enableSuperuserAccess: false and deploy again.

5. Confirm superuser is gone — Secret removed and network login fails:

   kubectl -n "$NS" get secret "${CLUSTER}-superuser" 2>&1 | grep -q NotFound
   # Optional: network login should fail (no superuser Secret / access disabled)
   kubectl -n "$NS" run cnpg-superuser-check --rm -i --restart=Never \
     --image=postgres:16-alpine --command -- \
     psql -h "${CLUSTER}-rw" -U postgres -d postgres -c 'SELECT 1' \
     || echo "expected failure"
   

6. Wire app DSN — store password in secret-values / app Secret; point the app at …-pg-rw. Do not leave enableSuperuserAccess: true overnight.

   Example DSN shape:

   postgresql+psycopg://contextforge:<APP_PASS>@wilix-one-platform-production-pg-rw:5432/contextforge
   

Emergency path: --mode exec

When superuser Secret is unavailable but you have kubectl exec on the primary pod, provision via local postgres OS user (no remote superuser login):

./scripts/cnpg-provision-db.sh \
  --namespace "$NS" \
  --cluster "$CLUSTER" \
  --db daytona \
  --role daytona \
  --password-from-env APP_PASS \
  --mode exec

This kubectl execs into the CNPG primary and runs psql -U postgres. Use only when secret mode is not an option; prefer the checklist above for planned provisioning.

In-cluster Job alternative

See .helm/jobs/cnpg-provision-db-job.yaml.example — an example Job that mounts …-pg-superuser. Not rendered by Helm; fill env vars and kubectl apply -f after step 2.

Related

• Platform cluster template: .helm/templates/postgres.yaml
• Database migration (dump/restore): docs/runbooks/cnpg-migrate-database.md (Task 5/6)
• Design spec: docs/superpowers/specs/2026-07-27-cnpg-platform-postgres-design.md