postgres-k8s-setup

Infrastructure skill. Deploys and manages PostgreSQL on Kubernetes using Bitnami Helm charts.

Scope

Does: Add Bitnami Helm repo. Deploy PostgreSQL with persistence. Run SQL migrations via kubectl exec. Verify pod and PVC health. Configure resource limits for Minikube.

Does NOT: Write application-level SQL queries. Configure replication or high-availability clusters. Set up pgBouncer connection pooling. Manage PostgreSQL extensions or plugins.

---

Tool Map

| Action | Script | Input | Output | |--------|--------|-------|--------| | Deploy PostgreSQL | scripts/deploy.sh | [--namespace] [--password] [--database] [--release] | Helm install output + connection info | | Verify deployment | scripts/verify.py | [--namespace] [--release] | JSON health report | | Run migrations | scripts/migrate.py | --sql-dir <path> [--host] [--port] [--database] [--user] [--password] | Migration execution report |

---

Execution Pattern (MCP Code Execution)

1. Agent reads this SKILL.md (~100 tokens)
2. Agent executes scripts sequentially: deploy -> verify -> migrate
3. Scripts run helm/kubectl commands (0 context tokens consumed)
4. Only the final result enters context

---

Default Configuration (Minikube-friendly)

# Single-node PostgreSQL
auth:
  postgresPassword: <user-provided or generated>
  database: appdb
primary:
  persistence:
    size: 2Gi
  resourcesPreset: small

---

Clarification Triggers

Required

1. Action -- deploy, verify, or run migrations?

Optional

2. Namespace -- target namespace (default: postgres)
3. Database name -- database to create (default: appdb)
4. Password -- postgres password (default: auto-generated by Helm)
5. SQL directory -- path to migration .sql files (required for migrate action)

---

Must Follow

• [ ] Always add bitnami repo before install: helm repo add bitnami https://charts.bitnami.com/bitnami
• [ ] Use --wait to ensure pods are ready before returning
• [ ] Verify all pods Running before running migrations
• [ ] Use resource-constrained settings for Minikube (persistence.size=2Gi)
• [ ] Run migration .sql files in alphabetical order for deterministic ordering

Must Avoid

• Hardcoding database passwords in scripts (pass via flags or env vars)
• Setting persistence size > 2Gi on Minikube without checking storage
• Running migrations before verifying pod readiness
• Skipping namespace creation before deployment

---

Cross-Platform Compatibility

# Goose recipe.yaml
name: postgres-k8s-setup
description: Deploy PostgreSQL on Kubernetes
steps:
  - run: bash .claude/skills/postgres-k8s-setup/scripts/deploy.sh
  - run: python .claude/skills/postgres-k8s-setup/scripts/verify.py
  - run: python .claude/skills/postgres-k8s-setup/scripts/migrate.py --sql-dir ./migrations