postgres
The platform's primary OLTP database. Holds every relational table the
runtime depends on — strategies, bots, runs, ledgers, the ownership
graph snapshot, the *_spec_versions tables for hash-locked specs,
workload_runs, terraform_runs, security_audit_events, and the
multi-tenant EntraTenantLink index.
Identity
| Field | Value |
|---|---|
| Service id | postgres |
| Role | database |
| Image | pgvector/pgvector:pg16 (compose) / ankane/pgvector:v0.5.1 (deployments/compose) — Postgres 16 + pgvector |
| Port | 5432 (in-cluster) / 5433 (host bind in compose to avoid clash with system Postgres) |
| Storage | 5 Gi PVC in StatefulSet (cell-local); RDS in aws-* templates; Cloud SQL in gcp-*; Azure DB in azure-* |
Deployment surfaces
| Surface | Where |
|---|---|
| Compose | service postgres in alphaswarm_platform/compose/docker-compose.yml |
| Kustomize | deployments/kubernetes/base-services/postgres-shared/ — StatefulSet + Service + ClusterSecretStore-backed credentials |
| Terraform module | alphaswarm_platform/terraform/modules/storage/ — RDS (AWS) / Cloud SQL (GCP) / Azure DB / containerised (local) |
| Companion module | alphaswarm_platform/terraform/modules/database/ — PgBouncer connection pooler + Alembic migration Job |
Dependencies
Upstream: none.
Downstream:
alphaswarm-core,alphaswarm-worker,alphaswarm-beat— primary read/write.alphaswarm-cp— workload + terraform ledger writes.alphaswarm-admin— admin ledger.mlflow— embedded postgres backend (or pointed at this one in prod).
Operations
- Migrations: Alembic runs as a one-shot Job in the
databaseTerraform module before the first app pod is scheduled. Migrations are immutable — seemigrations-persistence. - Backups: pg_dump cron + WAL archiving to MinIO/S3 (per cloud).
RPO 5 min, RTO 30 min; restore runbook at
how-to/runbooks/dr-restore.md. - Secrets: primary DSN in Vault → ExternalSecret → in-cluster Secret. Hand-pasted credentials are a review-blocking change.
- Connection pooling: PgBouncer (transaction mode) sits in front;
app pods connect through
pgbouncer.alphaswarm.svc.cluster.local:6432.
See also
migrations-persistence— Alembic immutability + ORM conventions.erd.md— entity-relationship map across every table this database holds.storageTerraform module — per-cloud provisioning.