Status: Accepted
Date: 2026-07
Author: Hamda Aden
The platform needs durable storage for build metadata: job history, artifact lineage, worker state, and audit logs. Options considered: PostgreSQL, SQLite, MongoDB, DynamoDB.
PostgreSQL 16 as the primary metadata store.
ACID guarantees. Build metadata requires strong consistency. A job that is marked complete must have its artifact record committed atomically. PostgreSQL's ACID semantics make this safe without application-level coordination.
Relational model fits the domain. Jobs have artifacts. Artifacts have versions. Workers process jobs. These are naturally relational. A document store would require denormalisation that adds complexity without benefit.
SQLite considered for local development. SQLite is used in the local Docker Compose stack for fast iteration. PostgreSQL is the production target. The application layer uses sqlx with standard database/sql so swapping the driver requires no application code changes.
MongoDB rejected. The flexible schema of MongoDB is not needed here — the job and artifact schemas are well-defined and stable. Adding a document store introduces operational complexity without benefit for this workload.
DynamoDB rejected. DynamoDB is appropriate for serverless or AWS-native architectures with unpredictable traffic patterns. This platform targets Kubernetes deployment where PostgreSQL operational patterns are well understood and Helm charts (CloudNativePG) handle HA and backup.
- PostgreSQL 16+ is a required infrastructure dependency in production
- SQLite is used in Docker Compose for local development only
- Database migrations managed with
golang-migrate - Connection pooling via
pgxpool— notdatabase/sqldirectly - CloudNativePG operator used for Kubernetes HA deployment (v0.4+)