0004. PostgreSQL for platform data

Status: accepted, 2026-10-09

Context

pages keeps JSON files. With teams, projects, nodes, quotas, and high-volume data (analytics, errors, AI usage, mail, metrics) the data becomes relational and write-heavy. Options: SQLite per service or PostgreSQL.

Decision

PostgreSQL only. One cluster per instance on the control-plane server, installed by xvii server install; one database and one role per service. pgx for access, sqlc for queries, migrations embedded and applied on start. SQLite is not supported (supporting two databases doubles testing for little gain).

Consequences

An install needs PostgreSQL (≈100 MB of RAM idle). The installer manages it; backups dump it.
Concurrent writers, real types, partitioning and full-text search are available to every service.
Managed databases that users create in apps are separate containers on nodes, never the platform cluster.