postgres

Overview ¶

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

It is the multi-node production target for the §9 persistence triad: the third leg, alongside the in-memory reference and the SQLite driver. Harbor inherits `internal/state/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.

Internal model:

• One row per (tenant, user, session, run, kind). The composite primary key is the identity quadruple plus Kind. RunID may be empty (session-scoped state); the column is NOT NULL but accepts the empty string.
• `bytes` is BYTEA — opaque payload, no JSONB constraint.
• `event_id` carries a UNIQUE secondary index for LoadByEventID and to defend against duplicate-id leaks under contention.
• Save is a transactional UPSERT (`INSERT ... ON CONFLICT DO UPDATE`) prefaced by an idempotency probe on `event_id`. When a slot already holds a different EventID, the previous EventID row is implicitly evicted because the slot's row is updated in place.
• `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, the driver is safe for concurrent reuse across N goroutines. The conformance suite's `Concurrent_SaveLoad_NoRace` + the local `concurrent_test.go` enforce this under -race.