docs(specs): draft S04 database spec

Suleimi Ahmedrequested to merge
4-spec-s04-database into main

Draft spec S04: Database — query layer, migrations, conventions.

Defines the database foundation for the Artifact Registry: PostgreSQL connectivity, migration framework (goose), type-safe query builder (jet), datastore layer conventions, developer tooling, integration testing pattern, and CI validation.

Companion to implementation MR !39 (merged). This spec captures decisions and conventions; !39 (merged) implements the tooling and libraries.

Key scope decisions

  • Library, not app lifecycle. How migrations integrate with HTTP server startup (goroutine, readiness gating) is deferred to S01.
  • Single DSN for bootstrap. PgBouncer split deferred until cluster topology is decided (tracked in #11).
  • No domain tables. Feature specs (S10-S18) introduce their own tables using the migration framework defined here.
  • Flat datastore package. Follows ADR-023: datastore.go (interfaces + shared ErrNotFound) and postgres.go (PostgreSQL implementation) co-located in one package.
Edited by Suleimi Ahmed

Merge request reports