postgres

Overview ¶

Package postgres is Harbor's V1 Postgres-backed ArtifactStore driver.

It is the fourth leg of the artifact persistence triad (in-memory floor, FS, SQLite, Postgres) defined by RFC §6.10 + §9. Phase 18 inherits `internal/artifacts/conformancetest.Run` verbatim — the suite IS the gate; this driver ships zero new conformance scenarios.

The driver uses `pgx/v5/stdlib` so the rest of Harbor sees a `database/sql.DB`. Parametric queries everywhere; no string concatenation into SQL (AGENTS.md §9). Advisory locks serialise the migration runner so multi-replica boots are race-free; the lock key is FNV-64a("harbor-artifacts-migrations"), distinct from Phase 16's StateStore lock so the two subsystems do not serialise against each other.

Internal model:

• One row per (tenant, user, session, task, namespace, id). The composite primary key is the artifact scope plus namespace + id. `task` may be empty (session-scoped artifacts); the column is NOT NULL but accepts the empty string.
• `bytes` is BYTEA — opaque payload, no JSONB constraint.
• `source_json` is BYTEA holding `json.Marshal`ed `Source map[string]any` from `PutOpts`.
• Put is a transactional flow: pre-INSERT SELECT of the existing row (returns it unchanged on dedup) followed by `INSERT ... ON CONFLICT DO NOTHING` followed by a final SELECT inside the same transaction. Concurrent writers of identical content land on the same row.
• `Close(ctx)` flips an atomic flag BEFORE calling `db.Close()` so subsequent calls fast-fail with `ErrStoreClosed` even while in-flight queries are draining.

Per AGENTS.md §5 (D-025), the driver is safe for concurrent reuse across N goroutines. The conformance suite's `Concurrent_PutGet_NoRace` + the local `concurrent_test.go` enforce this under -race.