feat(db): packages/db — schema, migrations, RLS (spec v0.4)

[OriginDevIT]

New @osds/db package: Kysely + pg, hand-written forward-only SQL migrations run by a small Kysely Migrator script, kysely-codegen (dev-only) for row types. Adds kysely + pg as runtime deps (approved). Authored against spec v0.4.

Scope

Tables 0001–0013, per the agreed list — nothing else yet:

tenants · tiers · categories · listing_categories · users · listings · claims · entitlements · slot_pools · slots · outbox

Rules applied

Rule	How
tenant_id + RLS on every table except tenants	ENABLE + FORCE row level security, policy tenant_id = osds_current_tenant_id() with WITH CHECK. Unset app.tenant_id ⇒ zero rows.
ULID text PKs, spec prefixes	tnt_ cat_ usr_ listing_ claim_ ent_ pool_ slot_, enforced with starts_with() CHECKs. Cross-table FKs are composite on (tenant_id, id) — a row can't reference another tenant's data.
postgis + pg_trgm in migration 1	plus helpers osds_current_tenant_id() and osds_set_updated_at().
listings generated tsvector (GIN) + geography (GiST)	search_tsv = weighted to_tsvector('simple', name/description); geog = ST_SetSRID(ST_MakePoint(lon,lat),4326)::geography; both STORED. pg_trgm GIN on name too.
timestamptz everywhere; money as integer minor units + ISO 4217	all timestamps timestamptz. No table in this scope stores money (billing is adapter-reported).
Forward-only, rollback note per header	no down(); each file's header carries a manual rollback note.

Slots — the approved hold design

slots has one row per unit of pool capacity; the row is the lock. A hold is one statement: UPDATE … FROM (SELECT id … WHERE status='available' OR (status='held' AND held_until < now()) ORDER BY (status='available') DESC, slot_no FOR UPDATE SKIP LOCKED LIMIT 1) at READ COMMITTED. N racers each lock a distinct row or get 0 rows ⇒ immediate "slot taken". Over-sell is impossible by construction. Shape CHECKs bind the nullable columns to status; slots_one_live_per_listing (partial unique) is the multi-tab backstop; slot_no is the stable featured-order ordinal. entitlements.slot_id FK is DEFERRABLE INITIALLY DEFERRED.

App role (migration 0013)

RLS is only enforced against a role that is not the table owner and lacks BYPASSRLS. osds_app is created NOLOGIN NOSUPERUSER NOBYPASSRLS with DML on the tenant tables + read-only spatial_ref_sys and nothing else. App/worker connect as it (DATABASE_URL); migrations run as the owner (DATABASE_URL_ADMIN). Granting it a login is a deployment step (touches authentication) — for local dev, infra/postgres/init/10-osds-app-role.sql does it on first cluster init. .env.example updated accordingly.

Verified

Every migration applied against postgis/postgis:16-3.4, then checked:

• extensions present; forced RLS on all 12 tables, off on tenants
• generated geog / search_tsv compute; GiST on geog, GIN on search_tsv + name trgm
• entitlements_slot_id_fkey is deferrable + deferred; partial unique / job indexes present
• SELECT/INSERT/UPDATE/DELETE shape CHECKs and consent NOT NULL reject bad rows
• as a non-owner role member of osds_app: tenant isolation holds, unset var ⇒ 0 rows, cross-tenant INSERT refused by WITH CHECK, CREATE TABLE denied, and the FOR UPDATE SKIP LOCKED hold query works (grabs slot 1, then 2, then 0 rows)

pnpm typecheck · pnpm lint · pnpm test (no test files) all pass.

Notes for review

• Migrations use .ts files executing raw SQL via Kysely's sql tag (one statement per call — the pg extended protocol forbids multi-statement strings). Tracked in kysely_migration.
• categories gets a cat_ ULID surrogate PK; the spec names category slugs but no PK scheme.
• claims.status / verification detail modelled behaviourally (spec §9 has no field-level schema).
• docker-compose.yml: postgres now mounts infra/postgres/init into docker-entrypoint-initdb.d. Existing pgdata volumes won't re-run it — README documents the one-liner / pnpm infra:reset.

🤖 Generated with Claude Code