110 lines
5.0 KiB
Markdown
110 lines
5.0 KiB
Markdown
---
|
|
id: pg-engine-schema
|
|
name: Postgres engine — schema bootstrap (engine-owned schema, table family)
|
|
status: pending
|
|
depends_on: []
|
|
scope: narrow
|
|
risk: low
|
|
impact: component
|
|
level: implementation
|
|
tags: [wave-4, postgres-engine]
|
|
---
|
|
|
|
## Description
|
|
|
|
Stand up the pg engine's data model: the engine-owned PostgreSQL schema
|
|
and its table family — the dependency root every later wave-4 task
|
|
rides. Per ADR-010 §8 (one engine-owned schema, default `alkstore`,
|
|
queues as rows — no per-queue tables/schemas) and engine-postgres.md's
|
|
mapping table.
|
|
|
|
A `schema.rs` module in `alkstore-postgres`:
|
|
|
|
- **Schema name is engine configuration** (default `alkstore`) — it
|
|
rides `PgOpts` (the open task wires it; this task's bootstrap takes
|
|
the schema name as an argument).
|
|
- **Bootstrap is idempotent DDL**, runnable at open on any connection:
|
|
`CREATE SCHEMA IF NOT EXISTS` + `CREATE TABLE IF NOT EXISTS` +
|
|
indexes. All engine-owned objects live in the one schema; consumer
|
|
tables co-tenant the instance untouched (deployment.md's co-tenancy
|
|
posture).
|
|
- **Table family** (column sets follow the contract's value shapes —
|
|
the `#[doc(hidden)]` constructors' full field lists in
|
|
`alkstore/src/{job,stream,schedule}.rs` are the field lists of
|
|
record; ADR-019 §1/§3, ADR-015 §3, ADR-009 §3, ADR-021 §2):
|
|
- **job table** (live rows — pending and processing): queue name,
|
|
payload, enqueue/ready-time resolution columns (`run_at`,
|
|
`expires_at`), `priority`, the stamped `QueueOpts` columns
|
|
(`visibility_timeout_s`, `max_attempts`, `backoff_base_s`,
|
|
`dead_letter_retention_s` — ADR-010 §3a), `attempts`,
|
|
`worker_id`, `claimed_at`, `claim_expires_at`, `last_error`.
|
|
Claim-ordering index per ADR-010's ordering row (`priority DESC,
|
|
run_at ASC, enqueue order`).
|
|
- **dead table**: the job row's diagnosis fields + `died_at`,
|
|
`last_error`; retention index for the sweep's retention
|
|
enforcement.
|
|
- **stream events table**: `id BIGSERIAL` (the offset — engine-
|
|
assigned, monotone, immutable, never renumbered), stream name,
|
|
nullable `key` column (carried metadata, ADR-015 §1), payload,
|
|
`created_at` (unix-seconds, informational). The `(stream, id)`
|
|
index serving the `offset ASC` read paths.
|
|
- **offsets table**: (stream, consumer) → offset, the monotone
|
|
checkpoint upsert target.
|
|
- **schedule table** (ADR-009): name (unique), `@every` spec, target
|
|
queue, payload, the `ScheduleOpts` stamps, and the boundary-state
|
|
columns the tick math advances (the substrate's
|
|
`__alkstore_scheduler_tasks` shape is the reference —
|
|
`reference-honker-machinery.md`).
|
|
- **locks table**: name (unique), owner, expiry timestamp — the TTL
|
|
lock machinery's storage (the substrate's lock-table semantics,
|
|
re-derived; the locks task builds ops on it).
|
|
- **Payload columns store the exact encoded bytes** (`bytea`) — not
|
|
`JSONB`: JSONB normalization (key reordering, duplicate folding)
|
|
would break the contract suite's byte-identical-rows row (ADR-020
|
|
§4). The engine stores exactly what `encode_payload` returned.
|
|
- **No notifications table** — pg notify is native (`pg_notify`); the
|
|
SQLite notify-table carriage has no pg counterpart. The 8000-byte
|
|
check is client-side (the seam task), not storage-shaped.
|
|
- **No migration machinery in v1** — tables are created fresh per
|
|
schema; append-column migrations are the substrate's evolution
|
|
discipline, not a greenfield v1 need (note the posture in the module
|
|
docs; wave 6's release pass revisits if the deployment story
|
|
demands in-place upgrades).
|
|
|
|
Tests use a raw `tokio_postgres::Connection`/Client against the
|
|
harness server (no engine code yet): bootstrap runs twice cleanly
|
|
(idempotence), every table exists with its pinned columns, the
|
|
bigserial offset behaves (monotone, gap-on-delete), the claim-ordering
|
|
index exists.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `schema.rs` with an idempotent `bootstrap(conn, schema_name)`
|
|
creating the full table family + indexes in the one schema
|
|
- [ ] Column sets match the contract's value shapes (the constructors'
|
|
field lists; stamp columns per ADR-010 §3a; `claimed_at` per
|
|
ADR-021 §2)
|
|
- [ ] Payload columns are `bytea` (exact-bytes posture, JSONB
|
|
rejected — documented in the module docs with the reason)
|
|
- [ ] Schema name is a parameter (default `alkstore` decided at the
|
|
`PgOpts` layer, next task)
|
|
- [ ] Idempotence + table-shape tests green against the harness server
|
|
- [ ] `cargo test -p alkstore-postgres`, clippy `-D warnings`, fmt clean
|
|
|
|
## References
|
|
|
|
- docs/architecture/engine-postgres.md (Identity and posture; mapping table)
|
|
- docs/architecture/decisions/010-queue-semantics-depth.md §3a, §8
|
|
- docs/architecture/decisions/015-streams-depth.md §1, §3
|
|
- docs/architecture/decisions/009-scheduler-collapse.md §3
|
|
- docs/architecture/deployment.md (co-tenancy)
|
|
- docs/research/reference-honker-machinery.md (schema reference read)
|
|
- alkstore/src/job.rs, stream.rs, schedule.rs (the field lists of record)
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |