@house-rules/domain-postgres 0.1.0 → 0.1.1

package/AGENTS.md

@@ -12,6 +12,8 @@ const Hosted = App.layer(AppHandlers).pipe(Layer.provide(fromEnv({ schema: "app"
 
 - `fromEnv({ schema })` reads `DOMAIN_STORE` (`postgres` by default, or `memory`) and `DATABASE_URL`. Declare both in the app's `.env.schema`.
 - `layer({ schema })` is the same store without the env switch; provide a `PgClient` yourself.
+- By default `layer` and `fromEnv` create the schema and tables on start. That needs CREATE on the database or schema. When the runtime role may only read and write rows, the schema owner runs `migrate(schema)` in the migration step, and the app passes `createTables: false`. Start then only checks the tables and dies with `TablesMissing`, naming the schema and missing tables, if any are absent.
+- The runtime role needs `USAGE` on the schema, `SELECT, INSERT, UPDATE, DELETE` on its tables, `USAGE` on its sequences (`outbox.position` is a `bigserial`), and `ALTER DEFAULT PRIVILEGES FOR ROLE <owner> IN SCHEMA <schema>` granting the same on tables and sequences the owner adds later. The README has the SQL.
 - Tests provide `platformForTests`: a fresh `test_<uuid>` schema per test, dropped after. Run the suite again with `DOMAIN_STORE=memory` to cover `Domain.InMemory`.
 
 ## Fixed rules

package/README.md

@@ -16,7 +16,7 @@ const Hosted = App.layer(AppHandlers).pipe(
 
 ## What it stores
 
-`layer` creates its tables in `schema` on start (`CREATE ... IF NOT EXISTS`):
+`layer` creates its tables in `schema` on start (`CREATE ... IF NOT EXISTS`), unless you pass `createTables: false` (see [A runtime role that cannot create](#a-runtime-role-that-cannot-create)):
 
 | Table | Holds |
 | --- | --- |
@@ -29,6 +29,26 @@ const Hosted = App.layer(AppHandlers).pipe(
 
 A command commits its events, state, receipt and outbox rows in one transaction. One loop per model delivers the outbox in order, deletes each row after its view or policy succeeds, retries a failure, and parks a row after `maxAttempts` (5) by setting `failed_at`. Views drop duplicates by checkpoint, so delivery is at least once.
 
+## A runtime role that cannot create
+
+Postgres checks the CREATE privilege before it checks whether a schema or table exists. So the default start, which runs `CREATE ... IF NOT EXISTS`, fails with `permission denied` for a role that may only read and write rows, even when every table is there.
+
+Split the two jobs. The schema owner runs `migrate(schema)` in the deploy's migration step, with a `PgClient` that connects as the owner. `migrate` is idempotent. The app runs `layer({ schema, createTables: false })` or `fromEnv({ schema, createTables: false })` as the runtime role. With `createTables: false`, start reads `pg_catalog` instead of creating anything. If the schema or any table is missing, the layer dies with `TablesMissing`, which names the schema and the missing tables. It never creates them.
+
+The runtime role needs these grants, run once by the owner:
+
+```sql
+GRANT USAGE ON SCHEMA app TO app_runtime;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA app TO app_runtime;
+GRANT USAGE ON ALL SEQUENCES IN SCHEMA app TO app_runtime;
+ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA app
+  GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_runtime;
+ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA app
+  GRANT USAGE ON SEQUENCES TO app_runtime;
+```
+
+The sequence grant covers `outbox.position`, a `bigserial`. The default privileges cover tables a later version of this package adds when the owner runs `migrate` again. The runtime role needs no CREATE on the database or the schema.
+
 ## Limits
 
 - One replica per database schema. Two processes would both run the outbox loop and each other's schedules, and live reads (`watch`) only see commits made in their own process.

package/dist/adapters/postgres-platform.d.ts

@@ -4,6 +4,7 @@ import * as Duration from "effect/Duration";
 import * as Layer from "effect/Layer";
 export interface Options {
     readonly schema?: string;
+    readonly createTables?: boolean;
     readonly pollInterval?: Duration.Input;
     readonly maxAttempts?: number;
 }

package/dist/adapters/postgres-platform.js

@@ -8,7 +8,7 @@ import * as Queue from "effect/Queue";
 import { makeAggregateStore } from "./aggregate-store.js";
 import { notifier } from "./host.js";
 import { makeOutbox } from "./outbox.js";
-import { migrate } from "./tables.js";
+import { checkTables, migrate } from "./tables.js";
 import { makeViewStore } from "./view-store.js";
 const unsupported = (kind) => Effect.die(new Error(`@house-rules/domain-postgres does not host ${kind} yet; use Domain.InMemory`));
 const makeHost = (sql, schema, model, scope, options) => Effect.gen(function* () {
@@ -60,7 +60,7 @@ const makeHost = (sql, schema, model, scope, options) => Effect.gen(function* ()
 export const layer = (options = {}) => Layer.effect(Platform, Effect.gen(function* () {
     const sql = yield* PgClient;
     const schema = options.schema ?? "domain";
-    yield* migrate(schema).pipe(Effect.orDie);
+    yield* (options.createTables === false ? checkTables(schema) : migrate(schema)).pipe(Effect.orDie);
     return Platform.of({
         model: ({ modelName }) => Effect.flatMap(Effect.scope, (scope) => makeHost(sql, schema, modelName, scope, options)),
     });

package/dist/adapters/tables.d.ts

@@ -1,4 +1,16 @@
 import { PgClient } from "@effect/sql-pg/PgClient";
 import * as Effect from "effect/Effect";
+export declare const tableNames: readonly ["instances", "events", "receipts", "schedules", "cancellations", "views", "view_keys", "view_entries", "outbox"];
+declare const TablesMissing_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "TablesMissing";
+} & Readonly<A>;
+export declare class TablesMissing extends TablesMissing_base<{
+    readonly schema: string;
+    readonly missing: ReadonlyArray<string>;
+    readonly message: string;
+}> {
+}
 export declare const createTables: (schema: string) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, PgClient>;
 export declare const migrate: (schema: string) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, PgClient>;
+export declare const checkTables: (schema: string) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError | TablesMissing, PgClient>;
+export {};

package/dist/adapters/tables.js

@@ -1,5 +1,19 @@
 import { PgClient } from "@effect/sql-pg/PgClient";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
+export const tableNames = [
+    "instances",
+    "events",
+    "receipts",
+    "schedules",
+    "cancellations",
+    "views",
+    "view_keys",
+    "view_entries",
+    "outbox",
+];
+export class TablesMissing extends Data.TaggedError("TablesMissing") {
+}
 export const createTables = (schema) => Effect.gen(function* () {
     const sql = yield* PgClient;
     const t = (name) => sql(`${schema}.${name}`);
@@ -94,3 +108,25 @@ export const migrate = (schema) => Effect.gen(function* () {
     const sql = yield* PgClient;
     yield* sql.withTransaction(createTables(schema));
 });
+export const checkTables = (schema) => Effect.gen(function* () {
+    const sql = yield* PgClient;
+    const schemas = yield* sql `
+      SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = ${schema}) AS found`;
+    const rows = yield* sql `
+      SELECT c.relname AS name
+      FROM pg_catalog.pg_class c
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ${schema} AND c.relkind IN ('r', 'p')`;
+    const found = new Set(rows.map((row) => row.name));
+    const missing = tableNames.filter((name) => !found.has(name));
+    if (missing.length === 0)
+        return;
+    const fix = `run migrate("${schema}") as the schema owner before starting with createTables: false`;
+    return yield* new TablesMissing({
+        schema,
+        missing,
+        message: schemas[0]?.found === true
+            ? `schema "${schema}" lacks tables ${missing.join(", ")}; ${fix}`
+            : `schema "${schema}" does not exist; ${fix}`,
+    });
+});

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { layer, type Options } from "./adapters/postgres-platform.ts";
-export { migrate } from "./adapters/tables.ts";
+export { migrate, TablesMissing } from "./adapters/tables.ts";
 export { domainStore, fromEnv, LOCAL_DATABASE_URL, PgForTests, platformForTests, testSchema, } from "./adapters/from-env.ts";

package/dist/index.js

@@ -1,3 +1,3 @@
 export { layer } from "./adapters/postgres-platform.js";
-export { migrate } from "./adapters/tables.js";
+export { migrate, TablesMissing } from "./adapters/tables.js";
 export { domainStore, fromEnv, LOCAL_DATABASE_URL, PgForTests, platformForTests, testSchema, } from "./adapters/from-env.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house-rules/domain-postgres",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A Postgres Platform for Alchemy Domain: events, state, views and an outbox in your own Postgres.",
   "license": "MIT",
   "type": "module",