Packages
@argus/db
The state store: the reviewer Postgres schema, its migration runner, and
typed repositories. It exists so idempotency (event dedup), statefulness
(thread conversations), and the audit trail all live behind small typed
APIs — and so every other package can test against pg-mem instead of a real
server.
Place in the system
The ingress uses EventLogRepo (dedup) and PrSessionRepo; the worker uses
all repos; argus-rules --database uses RulesetRepo;
bin/argus-migrate.ts runs the migrations. Depends on @argus/shared,
pg, and postgrator.
The schema (one table per concern)
| Table | Concern | Key columns |
|---|---|---|
reviewer.pr_session |
One row per PR Argus engaged with | (org, project, repo_id, pr_id) unique, last_reviewed_sha (incremental review), status (active / paused / closed — the pause switch) |
reviewer.thread |
One row per thread Argus participates in | finding_key (dedup across re-reviews), conversation JSONB (replayed on reply turns) |
reviewer.event_log |
Idempotency + audit | (subscription_id, notification_id) unique — the dedup key; outcome, model, prompt_sha, tokens_in/out, service_version |
reviewer.ruleset |
The rules registry | (scope_key, pack, version) unique, path_glob, content_sha, active |
reviewer.agent_comment |
The hourly comment ledger | backs the comment-rate cap |
Migrations
runMigrations() wraps postgrator over
packages/db/migrations/NNNN.do.*.sql (currently 0001–0007): applied
files are tracked in reviewer.schema_migrations, md5-checksummed, and
guarded by a Postgres advisory lock so concurrently booting replicas
serialise safely. Run via npm run db:migrate.
Applied migrations are md5-checksummed — editing one after it has run means
the file no longer matches its recorded checksum. Add the next
NNNN.do.*.sql instead; there are deliberately no .undo. files — roll
forward, never back.
Key exports
createPgPool() + the Queryable abstraction (everything queries through
it, which is what makes pg-mem substitutable), runMigrations(),
PrSessionRepo, ThreadRepo, EventLogRepo, RulesetRepo,
CommentLedgerRepo, and the zod enums (PrSessionStatusSchema,
EventOutcomeSchema).
How it's tested
db.test.ts runs the real migrations and every repo against pg-mem —
schema DDL, dedup conflict handling, session upserts, ruleset version
bumping — no Postgres server involved.