dzql 0.7.0 → 0.8.0

package/README.md

@@ -12,6 +12,22 @@ bun run db:rebuild
 bun run dev
 ```
 
+## delta's Postgres step
+
+dzql is becoming the Postgres step for apps built on [@blueshed/delta](https://github.com/blueshed/delta):
+a delta app grows from a JSON file to SQLite to Postgres, and on Postgres its documents are kept by
+dzql. Since 0.8.0 dzql carries delta's Postgres backend, with the same names, so moving is an
+import change:
+
+```ts
+import { applyFramework, applySql, createDocListener, docTypeFromDef, generateSql } from "dzql/postgres";
+import { openPglite } from "dzql/pglite";   // Postgres in this process
+import { jwtAuth } from "dzql/auth-jwt";
+```
+
+Its tests run delta's own cases (`@blueshed/delta/testing`) against it. Compiled SQL replaces the
+framework SQL in later releases; the plan is in Workshop's `docs/postgres-split-plan.md`.
+
 ## Documentation
 
 See the [full documentation](./docs/README.md) for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Database-first real-time framework with TypeScript support",
   "repository": {
     "type": "git",
@@ -14,7 +14,10 @@
     ".": "./src/runtime/index.ts",
     "./client": "./src/client/index.ts",
     "./compiler": "./src/cli/index.ts",
-    "./namespace": "./src/runtime/namespace.ts"
+    "./namespace": "./src/runtime/namespace.ts",
+    "./postgres": "./src/postgres/index.ts",
+    "./pglite": "./src/postgres/pglite.ts",
+    "./auth-jwt": "./src/postgres/auth-jwt.ts"
   },
   "files": [
     "src",
@@ -45,12 +48,16 @@
   "author": "Peter Bunyan",
   "license": "MIT",
   "dependencies": {
-    "postgres": "^3.4.3",
+    "@blueshed/delta": "^0.16.0",
+    "@electric-sql/pglite": "^0.5.4",
     "dotenv": "^16.4.5",
-    "jose": "^5.2.3"
+    "jose": "^6.2.4",
+    "pg": "^8.22.0",
+    "postgres": "^3.4.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/pg": "^8.20.0",
     "pinia": "^3.0.4",
     "typescript": "^5.0.0",
     "vue": "^3.5.26"

package/src/postgres/auth-jwt-sql.ts

@@ -0,0 +1,32 @@
+/**
+ * Auth-JWT SQL helpers — pure filesystem access, no jose dependency.
+ *
+ * These are split out of `auth-jwt.ts` so the `delta init` CLI (which only
+ * needs the file path) can run in projects that haven't installed jose.
+ * Consumers of the `@blueshed/delta/auth-jwt` subpath still get these via
+ * re-export from `auth-jwt.ts`.
+ */
+import type { Pool } from "pg";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const AUTH_JWT_SQL_PATH = join(import.meta.dir, "..", "sql", "auth-jwt.sql");
+
+/** Absolute path to the reference auth-jwt SQL file (users + register + login). */
+export function authJwtSqlFile(): string {
+  return AUTH_JWT_SQL_PATH;
+}
+
+/** The reference auth-jwt SQL as a string. */
+export function authJwtSql(): string {
+  return readFileSync(AUTH_JWT_SQL_PATH, "utf8");
+}
+
+/**
+ * Apply the reference users schema + login/register stored functions to a
+ * pool. Idempotent. Call once at boot alongside `applyFramework(pool)`, or
+ * use `delta init --with-auth` to copy the file for docker-entrypoint use.
+ */
+export async function applyAuthJwtSchema(pool: Pool): Promise<void> {
+  await pool.query(authJwtSql());
+}

package/src/postgres/auth-jwt.ts

@@ -0,0 +1,209 @@
+/**
+ * Auth-JWT — reference `DeltaAuth` implementation using JWTs (jose) and
+ * Postgres stored functions for credential verification.
+ *
+ * Ship this as an opt-in subpath: `@blueshed/delta/auth-jwt`. Users who want
+ * a different auth scheme (sessions, OAuth, magic links, none) implement
+ * their own `DeltaAuth` instead.
+ *
+ * Contract with Postgres:
+ *   - `login(email, password) RETURNS jsonb` — return a user row or NULL.
+ *   - `register(name, email, password) RETURNS jsonb` — return a user row,
+ *     raise unique_violation (23505) on duplicate email.
+ *
+ * Both are overridable via the `loginSql` / `registerSql` options.
+ *
+ *   import { jwtAuth } from "@blueshed/delta/auth-jwt";
+ *
+ *   const auth = jwtAuth({
+ *     pool,
+ *     secret: process.env.JWT_SECRET!,
+ *   });
+ *
+ *   wireAuth(ws, auth);
+ *   await createDocListener(ws, pool, { auth });
+ *
+ * SQL-file helpers (`authJwtSqlFile`, `authJwtSql`, `applyAuthJwtSchema`) live
+ * in `./auth-jwt-sql.ts` and are re-exported from here for convenience. They
+ * have no jose dependency, so the `delta init` CLI can load them without
+ * forcing consumers to install jose just to copy SQL files.
+ */
+import { SignJWT, jwtVerify, decodeJwt } from "jose";
+import type { Pool } from "pg";
+import { createLogger } from "@blueshed/delta/logger";
+import type { DeltaAuth } from "@blueshed/delta/auth";
+import { dropClientSubscriptions } from "@blueshed/delta/backend";
+
+/** Algorithm this module signs with — pinned on verify to prevent alg-confusion. */
+const JWT_ALG = "HS256";
+
+export {
+  authJwtSqlFile,
+  authJwtSql,
+  applyAuthJwtSchema,
+} from "./auth-jwt-sql";
+
+const log = createLogger("[auth-jwt]");
+
+export interface User {
+  id: number | string;
+  name?: string;
+  email?: string;
+  [key: string]: unknown;
+}
+
+export interface JwtAuthOpts {
+  pool: Pool;
+  secret: string | Uint8Array;
+  expirationTime?: string;
+  loginSql?: string;
+  registerSql?: string;
+  /**
+   * Optional re-validation hook for `authenticate`. A JWT is stateless: by
+   * default a signed, unexpired token grants access even if the user was
+   * since deleted or disabled (the documented trade-off of stateless auth).
+   * Provide `verifyUser` to re-check the identity against the database on
+   * each `authenticate`; return the (possibly refreshed) user to allow, or
+   * `null` to reject. Not called on `login` / `register` (those just hit the DB).
+   */
+  verifyUser?: (user: User, pool: Pool) => Promise<User | null>;
+}
+
+/** Set the socket's identity, tearing down a prior *different* identity's
+ *  live subscriptions so an identity switch on one socket can't keep
+ *  receiving the previous user's scoped docs. `expires` is when the token it
+ *  came from runs out (ms since the epoch); `gate` refuses it after that. */
+function switchIdentity(client: any, user: User, expires: number | undefined): void {
+  const prev = client.data?.identity as User | undefined;
+  if (prev && String(prev.id) !== String(user.id)) {
+    dropClientSubscriptions(client);
+  }
+  if (!client.data) client.data = {};
+  client.data.identity = user;
+  client.data.identityExpires = expires;
+}
+
+/** When a token's `exp` says it runs out, in ms since the epoch. */
+const expiresOf = (exp: unknown): number | undefined => (typeof exp === "number" ? exp * 1000 : undefined);
+
+export function jwtAuth(opts: JwtAuthOpts): DeltaAuth<User> {
+  const secret =
+    typeof opts.secret === "string"
+      ? new TextEncoder().encode(opts.secret)
+      : opts.secret;
+  const expirationTime = opts.expirationTime ?? "7d";
+  const loginSql = opts.loginSql ?? "SELECT login($1, $2) AS result";
+  const registerSql = opts.registerSql ?? "SELECT register($1, $2, $3) AS result";
+
+  async function signToken(user: User): Promise<string> {
+    return new SignJWT({
+      sub: String(user.id),
+      name: user.name,
+      email: user.email,
+    })
+      .setProtectedHeader({ alg: JWT_ALG })
+      .setIssuedAt()
+      .setExpirationTime(expirationTime)
+      .sign(secret);
+  }
+
+  async function verifyToken(token: string): Promise<{ user: User; expires: number | undefined } | null> {
+    try {
+      // Pin the algorithm allowlist — without it, jose accepts any alg the
+      // token header claims, opening an alg-confusion vector.
+      const { payload } = await jwtVerify(token, secret, { algorithms: [JWT_ALG] });
+      const id = payload.sub;
+      if (id === undefined) return null;
+      const user: User = {
+        id: /^\d+$/.test(String(id)) ? Number(id) : String(id),
+        name: payload.name as string | undefined,
+        email: payload.email as string | undefined,
+      };
+      return { user, expires: expiresOf(payload.exp) };
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    actions: {
+      async login(params, client) {
+        const { email, password } = params ?? {};
+        if (!email || !password) return { error: "email and password required" };
+        const { rows } = await opts.pool.query(loginSql, [email, password]);
+        const user = rows[0]?.result as User | null;
+        if (!user) return { error: "Invalid credentials" };
+        const token = await signToken(user);
+        switchIdentity(client, user, expiresOf(decodeJwt(token).exp));
+        log.info(`login user=${user.id}`);
+        return { result: { ...user, token } };
+      },
+
+      async register(params, client) {
+        const { name, email, password } = params ?? {};
+        if (!name || !email || !password) {
+          return { error: "name, email, and password required" };
+        }
+        try {
+          const { rows } = await opts.pool.query(registerSql, [name, email, password]);
+          const user = rows[0]?.result as User;
+          const token = await signToken(user);
+          switchIdentity(client, user, expiresOf(decodeJwt(token).exp));
+          log.info(`register user=${user.id}`);
+          return { result: { ...user, token } };
+        } catch (err: any) {
+          if (err.code === "23505") return { error: "Email already registered" };
+          throw err;
+        }
+      },
+
+      async authenticate(params, client) {
+        const { token } = params ?? {};
+        if (!token) return { error: "token required" };
+        const verified = await verifyToken(token);
+        if (!verified) return { error: "Invalid token" };
+        let user = verified.user;
+        if (opts.verifyUser) {
+          const checked = await opts.verifyUser(user, opts.pool);
+          if (!checked) return { error: "Invalid token" };
+          user = checked;
+        }
+        switchIdentity(client, user, verified.expires);
+        log.info(`authenticate user=${user.id}`);
+        return { result: user };
+      },
+
+      async logout(_params, client) {
+        const prev = client.data?.identity as User | undefined;
+        if (client.data) { delete client.data.identity; delete client.data.identityExpires; }
+        // Tear down the prior identity's live doc subscriptions so its scoped
+        // ops stop streaming to this socket immediately.
+        dropClientSubscriptions(client);
+        if (prev) log.info(`logout user=${prev.id}`);
+        return { result: { ack: true } };
+      },
+    },
+
+    gate(client) {
+      // A session lasts as long as its token: once it runs out the socket is
+      // signed out (and its documents let go), as a logout would do, and says
+      // so until it signs in again -- the listener asks the gate before it
+      // tells a socket of a change, too, so that is not always a request.
+      const expires = client.data?.identityExpires as number | undefined;
+      if (expires !== undefined && Date.now() >= expires) {
+        if (client.data.identity !== undefined) {
+          delete client.data.identity;
+          dropClientSubscriptions(client);
+        }
+        return { error: "Session expired: authenticate again" };
+      }
+      const identity = client.data?.identity as User | undefined;
+      if (!identity) return { error: "Authentication required" };
+      return identity;
+    },
+
+    asSqlArg(identity) {
+      return identity.id;
+    },
+  };
+}

package/src/postgres/auth.ts

@@ -0,0 +1,50 @@
+/**
+ * Postgres auth helpers — RLS session context for delta-doc queries.
+ *
+ * `withAppAuth(pool, sqlArg, fn)` checks out a client, opens a transaction,
+ * sets `app.user_id` for the duration of the transaction, runs `fn` with the
+ * client, then commits and releases. Row-Level Security policies that read
+ * `current_setting('app.user_id', true)` then filter automatically.
+ *
+ *   CREATE POLICY venues_owner ON venues
+ *     FOR ALL USING (owner_id = current_setting('app.user_id', true)::int);
+ *
+ *   await withAppAuth(pool, user.id, c =>
+ *     c.query("SELECT delta_open($1) AS doc", [docName]),
+ *   );
+ *
+ * The session variable is set via `SET LOCAL` so it reverts on transaction
+ * end — safe against pool reuse.
+ *
+ * Re-exports the `DeltaAuth` contract from `../auth` for convenience.
+ */
+import type { Pool, PoolClient } from "pg";
+
+export type { DeltaAuth, AuthError, AuthAction } from "@blueshed/delta/auth";
+export { isAuthError, wireAuth, upgradeWithAuth } from "@blueshed/delta/auth";
+
+/**
+ * Run `fn` inside a transaction with `SET LOCAL app.user_id = <sqlArg>`. All
+ * queries issued on the passed client observe RLS policies scoped to that
+ * identity.
+ */
+export async function withAppAuth<T>(
+  pool: Pool,
+  sqlArg: string | number,
+  fn: (c: PoolClient) => Promise<T>,
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    // SET LOCAL cannot be parameterised — use set_config(..., is_local=true).
+    await client.query("SELECT set_config('app.user_id', $1, true)", [String(sqlArg)]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (err) {
+    try { await client.query("ROLLBACK"); } catch { /* pool may already be closed */ }
+    throw err;
+  } finally {
+    client.release();
+  }
+}

package/src/postgres/bootstrap.ts

@@ -0,0 +1,55 @@
+/**
+ * Bootstrap helpers — apply the delta-doc framework SQL to a Postgres
+ * database, programmatically. Alternative to copying the files into a
+ * consumer's `init_db/` directory.
+ *
+ *   import { Pool } from "pg";
+ *   import { applyFramework } from "@blueshed/delta/postgres";
+ *
+ *   const pool = new Pool({ connectionString: process.env.PG_URL });
+ *   await applyFramework(pool);
+ *
+ * The framework SQL is idempotent (`CREATE … IF NOT EXISTS`,
+ * `ON CONFLICT DO UPDATE`) so it is safe to call on every server boot.
+ *
+ * For docker-entrypoint-initdb.d workflows, use the `delta init` CLI to
+ * copy the same files into a directory the image can mount.
+ */
+import type { Pool } from "pg";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const FRAMEWORK_SQL_DIR = join(import.meta.dir, "..", "sql");
+
+/** Absolute paths to the framework SQL files, in apply-order.
+ *  Filters to `001*-*.sql` — siblings like `auth-jwt.sql` are applied
+ *  separately (see `@blueshed/delta/auth-jwt` → `applyAuthJwtSchema`). */
+export function frameworkSqlFiles(): string[] {
+  return readdirSync(FRAMEWORK_SQL_DIR)
+    .filter((f) => /^001[a-z]?-.+\.sql$/.test(f))
+    .sort()
+    .map((f) => join(FRAMEWORK_SQL_DIR, f));
+}
+
+/**
+ * Apply the framework SQL to the given pool. Runs every `001*` file in
+ * `src/sql/` alphabetically — 001a through 001g today. Safe to call
+ * repeatedly (idempotent statements).
+ */
+export async function applyFramework(pool: Pool): Promise<void> {
+  for (const path of frameworkSqlFiles()) {
+    const sql = readFileSync(path, "utf8");
+    await pool.query(sql);
+  }
+}
+
+/**
+ * Apply an arbitrary SQL string to the pool (convenience wrapper). Useful
+ * for layering `generateSql(schema, docs)` output on top of the framework:
+ *
+ *   await applyFramework(pool);
+ *   await applySql(pool, generateSql(schema, docs));
+ */
+export async function applySql(pool: Pool, sql: string): Promise<void> {
+  if (sql.trim()) await pool.query(sql);
+}

package/src/postgres/carry.ts

@@ -0,0 +1,40 @@
+/**
+ * Carrying an app's rows into, and out of, a Postgres database -- a server, or
+ * PGlite in this process. The same `Snapshot` every backend gives and takes
+ * (`../../schema`), so the data moves along the path with its ids and
+ * sequences unchanged.
+ */
+import type { Pool } from "pg";
+import { isoTime, lastId, q, type Schema, type Snapshot } from "@blueshed/delta/backend";
+
+/** Every row of the schema's tables (every version of a temporal row), and each sequence's last id. */
+export async function exportTables(pool: Pool, schema: Schema): Promise<Snapshot> {
+  const tables: Snapshot["tables"] = {};
+  const sequences: Record<string, number> = {};
+  for (const [key, table] of Object.entries(schema.tables)) {
+    const order = table.temporal ? "id, valid_from" : "id";
+    const { rows } = await pool.query(`SELECT to_jsonb(t.*) AS row FROM ${q(table.name)} t ORDER BY ${order}`);
+    tables[key] = rows.map(({ row }: { row: Record<string, unknown> }) =>
+      table.temporal ? { ...row, valid_from: isoTime(row.valid_from), valid_to: isoTime(row.valid_to) } : row,
+    );
+    const seq = (await pool.query(`SELECT last_value, is_called FROM ${q(`seq_${table.name}`)}`)).rows[0];
+    sequences[key] = seq ? Number(seq.last_value) - (seq.is_called ? 0 : 1) : 0;
+  }
+  return { tables, sequences };
+}
+
+/**
+ * Put a snapshot's rows into the schema's tables, as they are (ids kept), and
+ * set each sequence past them, so the next row the database names follows the
+ * last one named where the rows came from. The tables should be empty.
+ */
+export async function importTables(pool: Pool, schema: Schema, snapshot: Snapshot): Promise<void> {
+  for (const [key, table] of Object.entries(schema.tables)) {
+    for (const row of snapshot.tables[key] ?? []) {
+      const value = table.temporal ? { valid_from: new Date().toISOString(), valid_to: null, ...row } : row;
+      await pool.query(`INSERT INTO ${q(table.name)} SELECT * FROM jsonb_populate_record(null::${q(table.name)}, $1)`, [JSON.stringify(value)]);
+    }
+    const last = lastId(snapshot, key);
+    await pool.query(`SELECT setval($1, $2, $3)`, [`seq_${table.name}`, Math.max(last, 1), last > 0]);
+  }
+}

package/src/postgres/codegen.ts

@@ -0,0 +1,172 @@
+/**
+ * Codegen — turn a TypeScript schema (`defineSchema`) and a set of doc
+ * definitions (`defineDoc`) into the SQL that registers both with the
+ * delta-doc framework.
+ *
+ * Output includes:
+ *   - CREATE SEQUENCE / CREATE TABLE (+ current_* view for temporal tables)
+ *   - Helper indexes
+ *   - INSERT INTO _delta_collections (columns_def, parent, temporal, cascade_on)
+ *   - INSERT INTO _delta_docs       (prefix, root_collection, include, scope)
+ *
+ * Everything is idempotent (CREATE … IF NOT EXISTS, ON CONFLICT DO UPDATE),
+ * so the same file can be re-applied to a live database after a schema change.
+ *
+ * Drive it from your project's `types.ts`:
+ *
+ *   import { generateSql } from "@blueshed/delta/postgres";
+ *   import { schema, docs } from "./types";
+ *   await Bun.write("init_db/003-tables.sql", generateSql(schema, docs));
+ *
+ * Or from the bundled CLI:
+ *
+ *   bunx delta sql ./types.ts --out init_db/003-tables.sql
+ */
+import type { Schema, DocDef } from "./schema";
+import { lit, columnSqlType, sqlDefault, findCascadeOn } from "./sql";
+import { defaultForType, q } from "@blueshed/delta/backend";
+import { assertScopeKeys } from "@blueshed/delta/backend";
+
+export interface GenerateSqlOptions {
+  /** Header comment included at the top of the file. */
+  header?: string;
+  /** Override the regenerate-command hint printed in the header. */
+  regenerate?: string;
+}
+
+export function generateSql(
+  schema: Schema,
+  docs: DocDef[],
+  opts: GenerateSqlOptions = {},
+): string {
+  const today = new Date().toISOString().slice(0, 10);
+  const header =
+    opts.header ?? "GENERATED FROM types.ts — DO NOT EDIT";
+  const regen = opts.regenerate ?? "bunx delta sql ./types.ts";
+
+  const lines: string[] = [
+    "-- =========================================================================",
+    `-- ${header}`,
+    `-- Generated: ${today}`,
+    `-- Regenerate: ${regen}`,
+    "-- =========================================================================",
+    "",
+  ];
+
+  for (const [key, table] of Object.entries(schema.tables)) {
+    const seqName = `seq_${table.name}`;
+    lines.push(`-- ${key}`);
+    lines.push(`CREATE SEQUENCE IF NOT EXISTS ${q(seqName)};`);
+    lines.push("");
+
+    const cols: string[] = [
+      `id BIGINT NOT NULL DEFAULT nextval(${lit(seqName)})`,
+    ];
+    if (table.parent) {
+      cols.push(`${q(table.parent.fkColumn)} BIGINT NOT NULL`);
+    }
+
+    for (const [col, def] of Object.entries(table.columns)) {
+      const sqlType = columnSqlType(def);
+      const notNull = def.nullable ? "" : " NOT NULL";
+      const defaultVal =
+        def.default !== undefined ? ` DEFAULT ${sqlDefault(def.default)}` : "";
+      cols.push(`${q(col)} ${sqlType}${notNull}${defaultVal}`);
+    }
+
+    if (table.temporal) {
+      cols.push("valid_from TIMESTAMPTZ NOT NULL DEFAULT NOW()");
+      cols.push("valid_to TIMESTAMPTZ");
+      cols.push("PRIMARY KEY (id, valid_from)");
+    } else {
+      cols.push("PRIMARY KEY (id)");
+    }
+
+    lines.push(`CREATE TABLE IF NOT EXISTS ${q(table.name)} (`);
+    lines.push(cols.map((c) => `  ${c}`).join(",\n"));
+    lines.push(");");
+    // A column a later schema declares, added to a table made before it (SQLite's migrateSchema): a
+    // no-op on a table just made. Nullable, with its default or its type's, as migrateSchema adds it.
+    if (table.parent) lines.push(`ALTER TABLE ${q(table.name)} ADD COLUMN IF NOT EXISTS ${q(table.parent.fkColumn)} BIGINT;`);
+    for (const [col, def] of Object.entries(table.columns)) {
+      const fill = def.default !== undefined ? def.default : def.nullable ? undefined : defaultForType(def.type);
+      lines.push(`ALTER TABLE ${q(table.name)} ADD COLUMN IF NOT EXISTS ${q(col)} ${columnSqlType(def)}${fill !== undefined ? ` DEFAULT ${sqlDefault(fill)}` : ""};`);
+    }
+    // Own the sequence to the table.id so `TRUNCATE RESTART IDENTITY`
+    // actually resets the counter — without this, re-seeds in tests and
+    // demo scripts drift by the stale sequence value.
+    lines.push(`ALTER SEQUENCE ${q(seqName)} OWNED BY ${q(table.name)}.id;`);
+
+    if (table.temporal) {
+      // security_invoker (Postgres 15+): the view reads as the caller, so the table's RLS holds through it
+      lines.push(
+        `CREATE OR REPLACE VIEW ${q("current_" + table.name)} WITH (security_invoker = true) AS SELECT * FROM ${q(table.name)} WHERE valid_to IS NULL;`,
+      );
+      lines.push(
+        `CREATE INDEX IF NOT EXISTS ${q("idx_" + table.name + "_id_valid")} ON ${q(table.name)} (id, valid_to);`,
+      );
+    }
+    if (table.parent) {
+      lines.push(
+        `CREATE INDEX IF NOT EXISTS ${q("idx_" + table.name + "_" + table.parent.fkColumn)} ON ${q(table.name)} (${q(table.parent.fkColumn)});`,
+      );
+    }
+    lines.push("");
+  }
+
+  // Collection metadata
+  lines.push("-- Collection metadata");
+  for (const [key, table] of Object.entries(schema.tables)) {
+    const cascadeOn = lit(JSON.stringify(findCascadeOn(key, schema)));
+    const colsDef = lit(JSON.stringify(table.columns));
+    const parent = table.parent ? lit(table.parent.collection) : "NULL";
+    const parentFk = table.parent ? lit(table.parent.fkColumn) : "NULL";
+    lines.push(
+      `INSERT INTO _delta_collections (collection_key, table_name, columns_def, parent_collection, parent_fk, temporal, cascade_on)`,
+    );
+    lines.push(
+      `  VALUES (${lit(key)}, ${lit(table.name)}, ${colsDef}, ${parent}, ${parentFk}, ${table.temporal}, ${cascadeOn})`,
+    );
+    lines.push(
+      `  ON CONFLICT (collection_key) DO UPDATE SET table_name = EXCLUDED.table_name, columns_def = EXCLUDED.columns_def,`,
+    );
+    lines.push(
+      `    parent_collection = EXCLUDED.parent_collection, parent_fk = EXCLUDED.parent_fk, temporal = EXCLUDED.temporal, cascade_on = EXCLUDED.cascade_on;`,
+    );
+  }
+  lines.push("");
+
+  // Doc definitions. `implied` is written when a document is implied (and
+  // then for each, so one that stops being implied is reset), and `held` when
+  // one names its columns (todo #70): SQL for an app with neither needs no
+  // framework SQL newer than it.
+  lines.push("-- Doc definitions");
+  const implied = docs.some((d) => d.implied);
+  const held = docs.some((d) => d.columns);
+  for (const doc of docs) assertScopeKeys(doc, schema);   // its scope's keys and the columns it names are its collections' columns
+  for (const doc of docs) {
+    // Build a proper Postgres text[] array literal: each element is wrapped in
+    // double quotes with embedded `"` and `\` backslash-escaped, so a comma or
+    // quote inside a collection key can't corrupt the array.
+    const include = doc.include.length
+      ? lit(
+          `{${doc.include
+            .map((e) => `"${e.replace(/(["\\])/g, "\\$1")}"`)
+            .join(",")}}`,
+        )
+      : "'{}'";
+    const scope = lit(JSON.stringify(doc.scope));
+    lines.push(
+      `INSERT INTO _delta_docs (prefix, root_collection, include, scope${implied ? ", implied" : ""}${held ? ", held" : ""})`,
+    );
+    lines.push(
+      `  VALUES (${lit(doc.prefix)}, ${lit(doc.root)}, ${include}, ${scope}${implied ? `, ${!!doc.implied}` : ""}${held ? `, ${lit(JSON.stringify(doc.columns ?? {}))}` : ""})`,
+    );
+    lines.push(
+      `  ON CONFLICT (prefix) DO UPDATE SET root_collection = EXCLUDED.root_collection, include = EXCLUDED.include, scope = EXCLUDED.scope${implied ? ", implied = EXCLUDED.implied" : ""}${held ? ", held = EXCLUDED.held" : ""};`,
+    );
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/postgres/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @blueshed/delta/postgres — Postgres backend for delta-doc.
+ *
+ * Schema + stored functions + LISTEN dispatch. Tables are generated from
+ * a TypeScript schema definition; all mutations go through stored functions
+ * that apply JSON-Patch ops and emit NOTIFY events. The doc-listener fans
+ * those events out to WebSocket subscribers.
+ *
+ *   import {
+ *     defineSchema, defineDoc,
+ *     createDocListener, docTypeFromDef,
+ *   } from "@blueshed/delta/postgres";
+ *
+ * The stored functions are `src/sql/001*.sql`: `applyFramework(pool)` applies
+ * them, or `bunx @blueshed/delta init <dir>` copies them for a migration tool
+ * (plain idempotent SQL; order is alphabetical).
+ */
+
+export {
+  defineSchema,
+  defineDoc,
+  loadDocAt,
+  pruneOpsLog,
+  validateOps,
+} from "./schema";
+export type {
+  ColumnDef,
+  TableDef,
+  Schema,
+  ResolvedTable,
+  DocDef,
+  ValidationError,
+} from "./schema";
+
+export { generateSql } from "./codegen";
+
+export { exportTables, importTables } from "./carry";
+export type { Snapshot } from "@blueshed/delta/backend";
+export type { GenerateSqlOptions } from "./codegen";
+
+export {
+  applyFramework,
+  applySql,
+  frameworkSqlFiles,
+} from "./bootstrap";
+
+export { migrate, migrationStatus, renameColumn, dropColumn, renameTable, fromFolder } from "./migrate";
+export type { Migration, MigrateOptions, MigrateResult, MigrationStatus } from "./migrate";
+
+export { createDocListener, defineCustomDoc } from "./listener";
+export type { CustomDocDef } from "./listener";
+
+export { docTypeFromDef } from "./registry";
+export type { DocType, Writer } from "./registry";
+
+export { withAppAuth } from "./auth";
+export type { DeltaAuth, AuthError, AuthAction } from "./auth";
+export { isAuthError, wireAuth, upgradeWithAuth } from "./auth";