postgres

Catalog date: 2026-06-24.

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	varies by deployment surface — see below; 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/ — a Deployment (not a StatefulSet) + Service + ClusterSecretStore-backed credentials, with a 20Gi PVC (pvc.yaml)
Terraform module (cloud)	alphaswarm_platform/terraform/modules/storage/ — RDS (AWS) / Cloud SQL (GCP) / Azure DB; for cloud_provider = "local"/"docker" it provisions a plain Docker container via the kreuzwerker/docker provider (no Kubernetes StatefulSet, no fixed Gi PVC size)
Terraform module (local k8s)	alphaswarm_platform/terraform/modules/alphaswarm_workloads/main.tf — a separate kubernetes_stateful_set.postgres resource, gated to local/RPi installs, pgvector/pgvector:pg16 image, 5Gi PVC. This is the actual "5 Gi PVC in StatefulSet" surface from an earlier version of this doc — it was miscategorized under terraform/modules/storage/.
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 database Terraform module before the first app pod is scheduled. Migrations are immutable — see the migrations-persistence rule in the private alphaswarm_internal repo.
• 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 (pool_mode = transaction) sits in front, per terraform/modules/database/main.tf; app pods connect through alphaswarm-pgbouncer.alphaswarm-system.svc.cluster.local:6432 (service name alphaswarm-pgbouncer in namespace alphaswarm-system — correcting the earlier pgbouncer.alphaswarm.svc.cluster.local hostname).

See also

• migrations-persistence (private alphaswarm_internal repo) — Alembic immutability + ORM conventions.
• erd.md — entity-relationship map across every table this database holds.
• storage Terraform module — per-cloud provisioning.