docs: propose ADR 0050, Module Database ABI v1 #68
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Zayin/Ekklesia#68
Reference in New Issue
Block a user
Proposes ADR 0050: Module Database ABI v1. Docs only.
What it decides
Core and modules exchange PostgreSQL SQL text, bound parameters, result rows with field metadata, and Core-owned transaction scopes. They never exchange ORM objects. Modules may use Drizzle, Kysely, raw SQL, or another module-side builder, and Core's own ORM becomes an implementation detail.
SET ROLE, or PostgreSQL roles.database.abi: 1. v8 is a hard cutover, like every manifest version. A v8 module withoutdatabasekeeps the legacyModuleDatabasefacade during the deprecation window. "Legacy module" means a v8 module on the legacy facade, never a v7 module. Already-built v7 packages must be rebuilt, and no v7/v8 manifest is parsed side by side.query({ text, values, rowMode })returns{ command, rowCount, rows, fields }. Each module gets its own executor.Uint8Array, and arrays of these. NoDate, no implicit JSON, no identifiers.int8,numeric, temporal types, and JSON arrive as text, with session DateStyle, IntervalStyle, and TimeZone fixed.byteaarrives as aUint8Array.ModuleDatabaseError { code, sqlState? }with no SQL, parameters, or driver text, recognised structurally.AbortSignal.pg-proxy), a raw-SQL tagged template, and later Kysely.is(PgTable),getTableConfig, orPgColumnon their objects.packageFormatstays 1. ABI v1 packages omittransitional.databaseRuntime, and the verifier refuses one that carries it.Relationship to earlier ADRs
Pickfacade definition and the one-shared-services-object rule.Accepted ADRs are not edited.
Changes
docs/architecture/decisions/0050-module-database-abi-v1.md: new, Proposed.docs/architecture/decisions/README.md: index entry.docs/architecture/platform-architecture.md: a one-sentence pointer from the packaging summary.No runtime, SDK, manifest, packaging, migration, CI, or Signage changes.
Verification
pnpm verifypasses.🤖 Generated with Claude Code
Core and modules exchange PostgreSQL SQL text, bound parameters, result rows with field metadata, and Core-owned transaction scopes. Never ORM objects. A module may use Drizzle, Kysely, raw SQL, or another module-side builder. Core's own ORM becomes an implementation detail. ADR 0050 decides: - an explicit correctness/compatibility boundary, not a security sandbox: no claim for SQL parsing, execution-time prefix checks, SET ROLE, or PostgreSQL roles; - opt-in through manifest version 8 `database.abi: 1`, a hard cutover like every manifest version; a version 8 module without `database` keeps the legacy ModuleDatabase facade during the deprecation window; - the executor: query({ text, values, rowMode }) returning { command, rowCount, rows, fields }, one executor per module; - a small parameter set (no Date, no implicit JSON, no identifiers); - a Core-owned decoding table that loses no precision and does not depend on time zones (int8, numeric, temporal, and JSON as text; bytea as Uint8Array); - a sanitized ModuleDatabaseError { code, sqlState? }, recognised structurally; - callback-scoped transactions and Core-named savepoints, revoked when their callback settles; - module-side adapters (Drizzle via pg-proxy, raw SQL, later Kysely); - plain schema metadata for ABI v1 modules instead of Drizzle objects; - migrations unchanged; packageFormat stays 1; ABI v1 packages omit transitional.databaseRuntime. It partly supersedes ADR 0016 and amends ADR 0007 for ABI v1 modules, and extends ADR 0049. Status Proposed. Accepted ADRs are unchanged. No runtime, SDK, manifest, packaging, migration, or Signage changes. Co-Authored-By: Claude Opus 5.5 <[email protected]>