dzql 0.8.0 → 0.9.0

package/docs/README.md

@@ -1,5 +1,11 @@
 # DZQL: Realtime Apps Without the Boilerplate
 
+> **The whole-stack dzql.** This describes dzql as it stood at 0.7: `domain.ts`, its runtime, the
+> typed client and the Pinia stores. They keep working until step 5 of Workshop's
+> `docs/postgres-split-plan.md` retires them. dzql is now delta's compiled Postgres step: a new app
+> starts on [@blueshed/delta](https://github.com/blueshed/delta) and comes to dzql through
+> `dzql/postgres` (`philo.md`, at the repo's root).
+
 DZQL compiles your data model into a complete realtime backend. Define entities and permissions in TypeScript, get a PostgreSQL database with CRUD operations, WebSocket sync, and type-safe client SDK - all generated.
 
 ## Why DZQL?

package/docs/for_ai.md

@@ -1,5 +1,11 @@
 # DZQL Domain Modeling Guide
 
+> **The whole-stack dzql.** This describes dzql as it stood at 0.7: `domain.ts`, its runtime, the
+> typed client and the Pinia stores. They keep working until step 5 of Workshop's
+> `docs/postgres-split-plan.md` retires them. dzql is now delta's compiled Postgres step: a new app
+> starts on [@blueshed/delta](https://github.com/blueshed/delta) and comes to dzql through
+> `dzql/postgres` (`philo.md`, at the repo's root).
+
 This guide defines patterns for generating valid DZQL domain definitions.
 
 ## Quick Reference

package/docs/project-setup.md

@@ -1,5 +1,11 @@
 # DZQL Project Setup Guide
 
+> **The whole-stack dzql.** This describes dzql as it stood at 0.7: `domain.ts`, its runtime, the
+> typed client and the Pinia stores. They keep working until step 5 of Workshop's
+> `docs/postgres-split-plan.md` retires them. dzql is now delta's compiled Postgres step: a new app
+> starts on [@blueshed/delta](https://github.com/blueshed/delta) and comes to dzql through
+> `dzql/postgres` (`philo.md`, at the repo's root).
+
 Complete guide for setting up a Vue/Pinia client project with DZQL.
 
 ## Quick Start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Database-first real-time framework with TypeScript support",
   "repository": {
     "type": "git",
@@ -17,7 +17,8 @@
     "./namespace": "./src/runtime/namespace.ts",
     "./postgres": "./src/postgres/index.ts",
     "./pglite": "./src/postgres/pglite.ts",
-    "./auth-jwt": "./src/postgres/auth-jwt.ts"
+    "./auth-jwt": "./src/postgres/auth-jwt.ts",
+    "./compile": "./src/compile/opens.ts"
   },
   "files": [
     "src",
@@ -29,7 +30,8 @@
   "scripts": {
     "test": "bun run test:setup && bun test; status=$?; bun run test:teardown; exit $status",
     "test:setup": "docker compose down -v && docker compose up -d --wait",
-    "test:teardown": "docker compose down -v"
+    "test:teardown": "docker compose down -v",
+    "bench": "bun run bench/run.ts"
   },
   "keywords": [
     "postgresql",
@@ -48,7 +50,6 @@
   "author": "Peter Bunyan",
   "license": "MIT",
   "dependencies": {
-    "@blueshed/delta": "^0.16.0",
     "@electric-sql/pglite": "^0.5.4",
     "dotenv": "^16.4.5",
     "jose": "^6.2.4",
@@ -56,14 +57,17 @@
     "postgres": "^3.4.3"
   },
   "devDependencies": {
+    "@blueshed/railroad": "^0.16.0",
     "@types/bun": "latest",
     "@types/pg": "^8.20.0",
     "pinia": "^3.0.4",
     "typescript": "^5.0.0",
-    "vue": "^3.5.26"
+    "vue": "^3.5.26",
+    "@blueshed/delta": "^1.0.0"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@blueshed/delta": "^1.0.0"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/cli/index.ts

@@ -14,6 +14,13 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
 
 const args = process.argv.slice(2);
+
+// delta's Postgres commands (dzql is delta's Postgres step): sql, init, migrate
+if (["sql", "init", "migrate"].includes(args[0] ?? "")) {
+  const { main } = await import("../postgres/cli.ts");
+  await main(args);
+  process.exit(0);
+}
 let command = args[0];
 let input = args[1];
 let outputDir = "dist"; // Default output directory

package/src/compile/opens.ts

@@ -0,0 +1,323 @@
+/**
+ * Compiled opens: delta's documents, read by SQL written for each one.
+ *
+ * `compileOpens(schema, docs)` turns an app's `defineSchema` / `defineDoc`
+ * into the reads of each document -- `dzql_open__<slug>(name)` and
+ * `dzql_open_at__<slug>(name, at)`, each with an `_as` for a signed-in caller --
+ * which the listener opens that document's names through (`docTypeFromDef`). Each answers what `delta_open`
+ * answers (the listener then shows it by the same schema), but its queries
+ * are written out: which
+ * table, which columns, how a collection hangs from the root, whether a row
+ * is temporal, what an implied root opens with. Nothing reads
+ * `_delta_collections` to find them.
+ *
+ * A name's scope is compiled too (`scopeOf`): its values read by position,
+ * each checked as its column takes it with the framework's own messages
+ * (`_delta_resolve_scope`), and its conditions written as typed SQL, so no
+ * query is built from text at run time. The version is still the
+ * framework's (`_delta_versions`).
+ *
+ * A pure function: the same definitions give the same text, byte for byte.
+ * A definition it cannot compile is an error naming the document, never SQL
+ * that half works.
+ */
+import { q, type ColumnDef, type DocDef, type ResolvedTable, type Schema } from "@blueshed/delta/backend";
+import { columnSqlType } from "../postgres/sql";
+
+/** A string as an SQL literal. */
+const lit = (s: string): string => `'${s.replace(/'/g, "''")}'`;
+
+/** A document's function name: its prefix, lower case, every other character `_`. */
+export function openFunction(prefix: string): string {
+  return `dzql_open__${prefix.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+}
+
+/**
+ * A row as a document reads it: as stored (a temporal row without its
+ * validity), so a column a later version added is there for the process that
+ * declares it -- each listener shows its own schema's (the schema is the
+ * contract; a database may hold more). Where the document names the columns it
+ * holds, those, its id and its parent key.
+ */
+function rowOf(table: ResolvedTable, doc: DocDef, coll: string, alias: string): string {
+  const held = doc.columns?.[coll];
+  if (held) {
+    const cols = ["id", ...(table.parent ? [table.parent.fkColumn] : []), ...Object.keys(table.columns).filter((c) => held.includes(c))];
+    return `jsonb_build_object(${cols.map((c) => `${lit(c)}, ${alias}.${q(c)}`).join(", ")})`;
+  }
+  return table.temporal ? `(to_jsonb(${alias}.*) - 'valid_from' - 'valid_to' - 'override')` : `to_jsonb(${alias}.*)`;
+}
+
+/** The rows of a temporal table that stand now, or at `at` (a time in the name): ` AND <condition>`; nothing for a table that is not temporal. */
+const standing = (table: ResolvedTable, alias: string, at = "p_at"): string =>
+  table.temporal
+    ? ` AND (CASE WHEN ${at} IS NULL THEN ${alias}.valid_to IS NULL ELSE ${alias}.valid_from <= ${at} AND (${alias}.valid_to IS NULL OR ${alias}.valid_to > ${at}) END)`
+    : "";
+
+/** An implied document's root before its row is there: its id and each column's default, as `_delta_implied_root` gives it. */
+function impliedRoot(table: ResolvedTable, doc: DocDef): string {
+  const held = doc.columns?.[doc.root];
+  const value = (d: ColumnDef): unknown =>
+    d.default !== undefined && d.default !== null ? d.default
+    : d.nullable ? null
+    : d.type === "text" ? ""
+    : d.type === "integer" || d.type === "real" ? 0
+    : d.type === "boolean" ? false
+    : null;
+  const fields = Object.entries(table.columns).filter(([c]) => !held || held.includes(c)).map(([c, d]) => [c, value(d)]);
+  return `jsonb_build_object('id', v_id) || ${lit(JSON.stringify(Object.fromEntries(fields)))}::jsonb`;
+}
+
+/**
+ * A collection a single document includes, held under its root row `v_id`:
+ * its rows joined up their parent chain to the root. A collection with no
+ * parent is held whole; one whose chain ends short of the root holds nothing.
+ */
+function includedSingle(schema: Schema, doc: DocDef, coll: string): string {
+  const table = need(schema, doc, coll);
+  if (!table.parent) return includedList(schema, doc, coll);
+  const joins: string[] = [];
+  let where = "";
+  let child = table;
+  let alias = "t";
+  for (let hop = 1; ; hop++) {
+    const parentKey = child.parent!.collection;
+    if (parentKey === doc.root) {
+      where = `${alias}.${q(child.parent!.fkColumn)} = v_id${standing(table, "t")}`;
+      break;
+    }
+    const parent = need(schema, doc, parentKey);
+    if (!parent.parent) return `'{}'::jsonb`;   // the chain ends short of the root: nothing of it is in the document
+    const p = `p${hop}`;
+    joins.push(`JOIN ${q(parent.name)} ${p} ON ${p}.id = ${alias}.${q(child.parent!.fkColumn)}${standing(parent, p)}`);
+    child = parent;
+    alias = p;
+  }
+  return `(SELECT COALESCE(jsonb_object_agg(t.id, ${rowOf(table, doc, coll, "t")}), '{}'::jsonb) FROM ${[`${q(table.name)} t`, ...joins].join(" ")} WHERE ${where})`;
+}
+
+/** A collection a list document includes: every row of it, as `_delta_load_collection_all` reads it. */
+function includedList(schema: Schema, doc: DocDef, coll: string): string {
+  const table = need(schema, doc, coll);
+  return `(SELECT COALESCE(jsonb_object_agg(t.id, ${rowOf(table, doc, coll, "t")}), '{}'::jsonb) FROM ${q(table.name)} t${standing(table, "t").replace(" AND", " WHERE")})`;
+}
+
+function need(schema: Schema, doc: DocDef, coll: string): ResolvedTable {
+  const table = schema.tables[coll];
+  if (!table) throw new Error(`[dzql compile] document ${doc.prefix} names a collection the schema does not have: ${coll}`);
+  return table;
+}
+
+/** The scope's parts: how a name's values are read and checked, and the conditions they set. */
+interface CompiledScope {
+  /** plpgsql variables. */
+  declare: string[];
+  /** plpgsql statements: read the name's values, check each, set v_single, v_id and p_at. */
+  body: string;
+  /** The conditions on the root's rows, as SQL over alias t ("" when none). */
+  conds: string;
+  /** Whether a name can make it one row: no scope (a name with an id), or an `id` equality. */
+  single: boolean;
+}
+
+const REAL = String.raw`^\s*[+-]?([0-9]+\.?[0-9]*|\.[0-9]+)(e[+-]?[0-9]+)?\s*$`;
+const WHOLE = String.raw`^\s*[+-]?[0-9]+\s*$`;
+const SAFE = String.raw`^\s*[+-]?0*[0-9]{1,16}\s*$`;
+const DAY = String.raw`^\s*([0-9]{4})-([0-9]{2})-([0-9]{2})\s*$`;
+
+/** Refuse a name's value: the framework's message, as a 400 (22P02). */
+const refuse = (message: string, value: string) => `RAISE EXCEPTION '${message.replace(/'/g, "''")}', ${value} USING ERRCODE = '22P02';`;
+
+/**
+ * A document's scope, compiled from its definition as `_delta_resolve_scope`
+ * reads it at run time: the name after the prefix split on ":" into its
+ * params' values (`id` first, the rest in alphabetical order), each binding
+ * taken in the order Postgres keeps a JSON object's keys (shorter first), a
+ * value its column cannot take refused with the same message, and an `id`
+ * equality making the document one row (single mode).
+ */
+function scopeOf(schema: Schema, doc: DocDef): CompiledScope {
+  const root = need(schema, doc, doc.root);
+  const entries = Object.entries(doc.scope ?? {});
+  if (entries.length === 0) {
+    return {
+      declare: ["v_rest TEXT;"],
+      body: `v_rest := substring(p_name FROM ${doc.prefix.length + 1});
+  v_single := v_rest <> '';
+  IF v_single THEN v_id := v_rest::BIGINT; END IF;`,
+      conds: "",
+      single: true,
+    };
+  }
+  const parsed = entries
+    .map(([key, binding]) => {
+      let m: RegExpExecArray | null;
+      if ((m = /^at:(.+)$/.exec(binding))) return { key, op: "at", param: m[1]! };
+      if ((m = /^like:(.+)$/.exec(binding))) return { key, op: "like", param: m[1]! };
+      if ((m = /^([<>=!]+):(.+)$/.exec(binding))) {
+        if (!["=", ">=", "<=", ">", "<", "!="].includes(m[1]!)) throw new Error(`[dzql compile] document ${doc.prefix}: invalid scope operator "${m[1]}" (valid: =, >=, <=, >, <, !=, like, at)`);
+        return { key, op: m[1]!, param: m[2]! };
+      }
+      return { key, op: "=", param: binding.replace(/^:+/, "") };
+    })
+    .sort((a, b) => a.key.length - b.key.length || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));   // jsonb's order of keys
+  const params = [...new Set(parsed.map((p) => p.param))].sort((a, b) => (a === "id" ? -1 : b === "id" ? 1 : a < b ? -1 : a > b ? 1 : 0));
+  const declare = ["v_parts TEXT[];", "v_date TEXT[];"];
+  const body: string[] = [`v_parts := string_to_array(substring(p_name FROM ${doc.prefix.length + 1}), ':');`, "v_single := FALSE;"];
+  const conds: string[] = [];
+  parsed.forEach(({ key, op, param }, i) => {
+    const v = `v_s${i + 1}`;
+    declare.push(`${v} TEXT;`);
+    body.push(`${v} := NULLIF(v_parts[${params.indexOf(param) + 1}], '');`);
+    const isKey = op !== "at" && (key === "id" || key === root.parent?.fkColumn);
+    const def = root.columns[key];
+    if (op === "at") {
+      body.push(dayOf(v, key), `IF ${v} IS NOT NULL THEN p_at := ${v}::TIMESTAMPTZ; END IF;`);
+      return;
+    }
+    if (!isKey && !def) throw new Error(`[dzql compile] document ${doc.prefix}: scope key "${key}" is not a column of "${doc.root}"`);
+    if (op === "like") {
+      conds.push(`(${v} IS NULL OR t.${q(key)} ILIKE ${v} || '%')`);
+      return;
+    }
+    const sqlOp = op === "!=" ? "<>" : op;
+    if (isKey) {
+      const n = `v_n${i + 1}`;
+      declare.push(`${n} BOOLEAN;`);
+      body.push(`IF ${v} IS NOT NULL THEN
+    IF ${v} ~ '${WHOLE}' THEN
+      IF ${v} !~ '${SAFE}' THEN ${refuse(`${key} % is past 2^53 - 1, which no number holds exactly`, v)}
+      ELSIF abs(${v}::numeric) > 9007199254740991 THEN ${refuse(`${key} % is past 2^53 - 1, which no number holds exactly`, v)}
+      END IF;
+      ${n} := TRUE;
+    ELSIF ${v} ~* '${REAL}' THEN
+      ${refuse(`${key} must be an id -- a whole number, or text -- not "%"`, v)}
+    ELSE
+      ${n} := FALSE;
+    END IF;
+  END IF;`);
+      // text no row has as an id: after every number, as SQLite orders it
+      const asText = ["!=", "<", "<="].includes(op) ? `t.${q(key)} IS NOT NULL` : "FALSE";
+      conds.push(`(${v} IS NULL OR (CASE WHEN ${n} THEN t.${q(key)} ${sqlOp} ${v}::BIGINT ELSE ${asText} END))`);
+      if (key === "id" && op === "=") body.push(`IF ${v} IS NOT NULL THEN v_single := TRUE; v_id := ${v}::BIGINT; END IF;`);
+      return;
+    }
+    if (def!.type === "integer") {
+      body.push(`IF ${v} IS NOT NULL THEN
+    IF ${v} !~ '${SAFE}' THEN ${refuse(`${key} must be an integer, not "%"`, v)}
+    ELSIF abs(${v}::numeric) > 9007199254740991 THEN ${refuse(`${key} must be an integer, not "%"`, v)}
+    END IF;
+  END IF;`);
+    } else if (def!.type === "real") {
+      body.push(`IF ${v} IS NOT NULL THEN
+    IF ${v} !~* '${REAL}' THEN ${refuse(`${key} must be a number, not "%"`, v)} END IF;
+    BEGIN
+      PERFORM ${v}::float8;
+    EXCEPTION WHEN numeric_value_out_of_range THEN
+      ${refuse(`${key} must be a number, not "%"`, v)}
+    END;
+  END IF;`);
+    } else if (def!.type === "timestamptz") {
+      body.push(dayOf(v, key));
+    }
+    conds.push(`(${v} IS NULL OR t.${q(key)} ${sqlOp} ${v}::${columnSqlType(def!)})`);
+  });
+  return { declare, body: body.join("\n  "), conds: conds.join(" AND "), single: parsed.some((p) => p.key === "id" && p.op === "=") };
+}
+
+/** A date, YYYY-MM-DD, that the calendar has, read as the instant midnight UTC begins it; anything else refused. */
+function dayOf(v: string, key: string): string {
+  return `IF ${v} IS NOT NULL THEN
+    v_date := regexp_match(${v}, '${DAY}');
+    IF v_date IS NULL OR v_date[1]::int < 1 OR v_date[2]::int NOT BETWEEN 1 AND 12 THEN
+      ${refuse(`${key} must be a date, YYYY-MM-DD, not "%"`, v)}
+    ELSIF v_date[3]::int NOT BETWEEN 1 AND extract(day FROM make_date(v_date[1]::int, v_date[2]::int, 1) + interval '1 month - 1 day')::int THEN
+      ${refuse(`${key} must be a date, YYYY-MM-DD, not "%"`, v)}
+    END IF;
+    ${v} := format('%s-%s-%s 00:00:00+00', v_date[1], v_date[2], v_date[3]);
+  END IF;`;
+}
+
+/** A document's function for `open_at`: the document as it stood at a time the caller gives. */
+export const openAtFunction = (prefix: string): string => openFunction(prefix).replace(/^dzql_open__/, "dzql_open_at__");
+
+/**
+ * One document's read, as `open` (`delta_open`: the time is the name's, an implied
+ * root opens with its defaults, the version is kept) or as `open_at`
+ * (`delta_open_at`: the time is the caller's, a root not there is null, no version).
+ */
+function readOf(schema: Schema, doc: DocDef, at: boolean): string {
+  const root = need(schema, doc, doc.root);
+  const rootJson = rowOf(root, doc, doc.root, "t");
+  const fields = (included: (coll: string) => string) =>
+    doc.include.map((c) => ` || jsonb_build_object(${lit(c)}, ${included(c)})`).join("");
+  const emptyIncludes = doc.include.map((c) => ` || jsonb_build_object(${lit(c)}, '{}'::jsonb)`).join("");
+  const fn = at ? openAtFunction(doc.prefix) : openFunction(doc.prefix);
+  const scope = scopeOf(schema, doc);
+  const where = (first: string[]) => [...first, ...(scope.conds ? [scope.conds] : [])].join(" AND ") || "TRUE";
+  const params = at ? "p_name TEXT, p_given TIMESTAMPTZ" : "p_name TEXT";
+  const missing = !at && doc.implied ? `v_doc := jsonb_build_object(${lit(doc.root)}, ${impliedRoot(root, doc)})${emptyIncludes};` : "RETURN NULL;";
+  const done = at
+    ? "RETURN v_doc;"
+    : `INSERT INTO _delta_versions (doc_name, version) VALUES (p_name, 0) ON CONFLICT (doc_name) DO NOTHING;
+  SELECT version INTO v_version FROM _delta_versions WHERE doc_name = p_name;
+  RETURN v_doc || jsonb_build_object('_version', v_version);`;
+  return `CREATE OR REPLACE FUNCTION ${fn}(${params})
+RETURNS JSONB AS $$
+DECLARE
+  p_at     TIMESTAMPTZ;
+  v_single BOOLEAN;
+  v_id     BIGINT;
+  v_rows   JSONB;
+  v_root   JSONB;
+  v_doc    JSONB;
+  v_version BIGINT;
+  ${scope.declare.join("\n  ")}
+BEGIN
+  ${scope.body}${at ? "\n  p_at := p_given;" : ""}
+  ${scope.single ? "IF NOT v_single THEN\n    " : ""}SELECT COALESCE(jsonb_object_agg(t.id, ${rootJson}), '{}'::jsonb) INTO v_rows FROM ${q(root.name)} t WHERE ${where([])}${standing(root, "t")};
+  ${scope.single ? "  " : ""}v_doc := jsonb_build_object(${lit(doc.root)}, v_rows)${fields((c) => includedList(schema, doc, c))};${scope.single ? `
+  ELSE
+    SELECT ${rootJson} INTO v_root FROM ${q(root.name)} t WHERE ${where(["t.id = v_id"])}${standing(root, "t")};
+    IF v_root IS NULL THEN
+      ${missing}
+    ELSE
+      v_doc := jsonb_build_object(${lit(doc.root)}, v_root)${fields((c) => includedSingle(schema, doc, c))};
+    END IF;
+  END IF;` : ""}
+  ${done}
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION ${fn}_as(p_user_id TEXT, ${params})
+RETURNS JSONB AS $$
+BEGIN
+  PERFORM set_config('app.user_id', p_user_id, true);
+  RETURN ${fn}(${at ? "p_name, p_given" : "p_name"});
+END
+$$ LANGUAGE plpgsql;`;
+}
+
+/** One document's reads: its open and its open_at, each with its `_as`. */
+function openOf(schema: Schema, doc: DocDef): string {
+  return `-- ${doc.prefix}: root ${doc.root}${doc.include.length ? `, includes ${doc.include.join(", ")}` : ""}${doc.implied ? ", implied" : ""}${doc.columns ? `, holds ${Object.entries(doc.columns).map(([c, cs]) => `${c}(${cs.join(", ")})`).join(" ")}` : ""}
+${readOf(schema, doc, false)}
+
+${readOf(schema, doc, true)}`;
+}
+
+/** The SQL that reads each of `docs` over `schema`: its open and its open_at, each with an `_as` for a signed-in caller. */
+export function compileOpens(schema: Schema, docs: DocDef[]): string {
+  const names = new Map<string, string>();
+  for (const doc of docs) {
+    const fn = openFunction(doc.prefix);
+    const other = names.get(fn);
+    if (other !== undefined) throw new Error(`[dzql compile] documents ${other} and ${doc.prefix} would share the function ${fn}`);
+    names.set(fn, doc.prefix);
+  }
+  return [
+    "-- Compiled by dzql from the app's defineSchema / defineDoc. Do not edit: compile again.",
+    ...docs.map((d) => openOf(schema, d)),
+    "",
+  ].join("\n\n");
+}

package/src/postgres/cli.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env bun
+/**
+ * dzql's Postgres commands, as delta's CLI had them: `dzql sql`, `dzql init`
+ * and `dzql migrate` (a postgres:// URL or a PGlite directory). Run through
+ * `dzql <command>` (src/cli/index.ts hands these three here).
+ */
+import { parseArgs } from "node:util";
+import { resolve, basename, join, dirname } from "node:path";
+import { mkdirSync, copyFileSync, existsSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { generateSql } from "./codegen";
+import { frameworkSqlFiles } from "./bootstrap";
+import { authJwtSqlFile } from "./auth-jwt-sql";
+import type { Schema, DocDef } from "./index";
+
+const PKG_VERSION = (() => {
+  try {
+    return String(JSON.parse(readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8")).version ?? "0.0.0");
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+const USAGE =
+    `Usage:\n` +
+    `  dzql sql <module> [--out <file>] [--force] [--schema-export <name>] [--docs-export <name>]\n` +
+    `  dzql init <dir> [--with-auth] [--upgrade]\n` +
+    `  dzql migrate <database> [--app <name>] [--dir <migrations>] [--status] [--json]\n` +
+    `        <database>: a PGlite directory or a postgres:// URL; --dir defaults to ./migrations\n` +
+    `\n` +
+    `Exit codes: 0 done, 1 an error, 2 a bad argument.\n`;
+
+let json = process.argv.includes("--json");
+
+const print = (result: unknown) => process.stdout.write(JSON.stringify(result ?? null, null, json ? undefined : 2) + "\n");
+
+function fail(err: unknown, exit = 1): never {
+  const error = { code: 0, message: err instanceof Error ? err.message : String(err) };
+  process.stderr.write((json ? JSON.stringify({ error }) : `dzql: ${error.message}`) + "\n");
+  process.exit(exit);
+}
+
+function usageError(why: string, show = false): never {
+  if (show && !json) process.stderr.write(USAGE + "\n");
+  fail(why, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Header handling — identifies files written by dzql init (stamped with this
+// package's version) so upgrades can read them back and avoid clobbering
+// user-owned SQL, and a `diff -u` against a later `init --upgrade` shows what changed.
+// ---------------------------------------------------------------------------
+
+// a file `delta init` vendored (stamped @blueshed/delta) is older than any of dzql's: always upgraded
+const HEADER_RE = /^-- @blueshed\/(delta|dzql) ([a-z0-9-]+) v(\d+\.\d+\.\d+)/;
+
+function readHeader(path: string): { pkg: string; kind: string; version: string } | null {
+  if (!existsSync(path)) return null;
+  const first = readFileSync(path, "utf8").split("\n", 1)[0] ?? "";
+  const m = first.match(HEADER_RE);
+  return m ? { pkg: m[1]!, kind: m[2]!, version: m[3]! } : null;
+}
+
+function writeWithHeader(src: string, dest: string, kind: "framework" | "auth-jwt"): void {
+  const header =
+    `-- @blueshed/dzql ${kind} v${PKG_VERSION}\n` +
+    `-- Vendored by 'dzql init'. Safe to read; prefer 'dzql init --upgrade' over hand edits.\n\n`;
+  writeFileSync(dest, header + readFileSync(src, "utf8"));
+}
+
+/**
+ * Back up `dest` to `dest + ".bak"` without destroying a pre-existing backup.
+ * If `dest.bak` already exists, fall back to `.bak.1`, `.bak.2`, … so an
+ * earlier backup the user may still need is preserved. Returns the path the
+ * backup was written to.
+ */
+function backupFile(dest: string): string {
+  let bak = dest + ".bak";
+  if (existsSync(bak)) {
+    let n = 1;
+    while (existsSync(`${dest}.bak.${n}`)) n++;
+    bak = `${dest}.bak.${n}`;
+    process.stderr.write(
+      `Note: ${basename(dest)}.bak already exists; backing up to ${basename(bak)} instead.\n`,
+    );
+  }
+  copyFileSync(dest, bak);
+  return bak;
+}
+
+// ---------------------------------------------------------------------------
+// dzql sql
+// ---------------------------------------------------------------------------
+
+// Stable substring of the codegen header (see codegen.ts:
+// "GENERATED FROM types.ts — DO NOT EDIT"). Matching on the leading words
+// avoids depending on the em-dash byte sequence.
+const GENERATED_MARKER = "GENERATED FROM";
+
+async function cmdSql(modulePath: string | undefined, values: Record<string, unknown>) {
+  if (!modulePath) usageError("sql takes a <module>", true);
+
+  const abs = resolve(process.cwd(), modulePath);
+  let mod: Record<string, unknown>;
+  try {
+    mod = await import(abs);
+  } catch (err) {
+    // Bun surfaces a `ResolveMessage` whose `.message` is a single useful line
+    // (e.g. "Cannot find module '…'") but is fronted by the class-name prefix;
+    // strip it to a clean one-liner instead of dumping the raw object/stack.
+    const raw =
+      err instanceof Error ? err.message.split("\n", 1)[0] : String(err);
+    const reason = raw.replace(/^(ResolveMessage|BuildMessage|Error):\s*/, "");
+    process.stderr.write(`Cannot load module "${modulePath}": ${reason}\n`);
+    process.exit(2);
+  }
+
+  const schemaExport = values["schema-export"] as string;
+  const docsExport = values["docs-export"] as string;
+  const schema = mod[schemaExport] as Schema | undefined;
+  const docs = mod[docsExport] as DocDef[] | undefined;
+
+  if (!schema || typeof schema !== "object" || !("tables" in schema)) {
+    process.stderr.write(
+      `Module at ${modulePath} does not export a Schema as \`${schemaExport}\`.\n` +
+      `Export one with: export const ${schemaExport} = defineSchema({ ... });\n`,
+    );
+    process.exit(2);
+  }
+  if (!Array.isArray(docs)) {
+    process.stderr.write(
+      `Module at ${modulePath} does not export a DocDef[] as \`${docsExport}\`.\n` +
+      `Export one with: export const ${docsExport} = [defineDoc(...), ...];\n`,
+    );
+    process.exit(2);
+  }
+
+  const sql = generateSql(schema, docs);
+  const out = values.out as string | undefined;
+  const force = !!values.force;
+
+  if (out) {
+    const absOut = resolve(out);
+    // Guard: never silently clobber a file we didn't generate. A previously
+    // generated file carries the codegen header marker and is safe to replace;
+    // anything else needs --force.
+    if (existsSync(absOut) && !force) {
+      const existing = readFileSync(absOut, "utf8");
+      if (!existing.includes(GENERATED_MARKER)) {
+        process.stderr.write(
+          `Refusing to overwrite ${out}: it has no generated-file header ` +
+          `(not produced by 'dzql sql').\n` +
+          `Pass --force to overwrite it anyway.\n`,
+        );
+        process.exit(3);
+      }
+      // It's a previously generated file — back it up before replacing.
+      backupFile(absOut);
+    }
+    mkdirSync(dirname(absOut), { recursive: true });
+    await Bun.write(out, sql);
+    process.stderr.write(`Wrote ${out} (${sql.length} bytes)\n`);
+  } else {
+    process.stdout.write(sql);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// dzql init
+// ---------------------------------------------------------------------------
+
+function cmdInit(dir: string | undefined, values: Record<string, unknown>) {
+  if (!dir) usageError("init takes a <dir>", true);
+
+  const absDir = resolve(process.cwd(), dir);
+  mkdirSync(absDir, { recursive: true });
+
+  const upgrade = !!values.upgrade;
+  const plan: { src: string; dest: string; kind: "framework" | "auth-jwt" }[] =
+    frameworkSqlFiles().map((src) => ({ src, dest: join(absDir, basename(src)), kind: "framework" }));
+  if (values["with-auth"]) plan.push({ src: authJwtSqlFile(), dest: join(absDir, "002-users.sql"), kind: "auth-jwt" });
+
+  // On upgrade we refuse to clobber files that don't have our header or that
+  // point to a newer version than we ship. The user either wrote that file
+  // themselves or has downgraded the package.
+  if (upgrade) {
+    const conflicts: string[] = [];
+    for (const { dest } of plan) {
+      if (!existsSync(dest)) continue;
+      const hdr = readHeader(dest);
+      if (!hdr) conflicts.push(`${basename(dest)}: not stamped by dzql init (or delta init)`);
+      else if (hdr.pkg === "dzql" && compareVersion(hdr.version, PKG_VERSION) > 0) {
+        conflicts.push(`${basename(dest)}: has v${hdr.version}, package is v${PKG_VERSION}`);
+      }
+    }
+    if (conflicts.length) {
+      process.stderr.write(
+        `Refusing to upgrade:\n  ${conflicts.join("\n  ")}\n\n` +
+        `Resolve these manually (move or rename the offending files) and rerun.\n`,
+      );
+      process.exit(3);
+    }
+  }
+
+  const created: string[] = [];
+  const upgraded: string[] = [];
+  const unchanged: string[] = [];
+
+  for (const { src, dest, kind } of plan) {
+    if (existsSync(dest)) {
+      const hdr = readHeader(dest);
+      if (!upgrade || (hdr?.pkg === "dzql" && hdr.version === PKG_VERSION)) {
+        unchanged.push(basename(dest));
+        continue;
+      }
+      const bak = backupFile(dest);
+      writeWithHeader(src, dest, kind);
+      upgraded.push(`${basename(dest)} (backup at ${basename(bak)})`);
+    } else {
+      writeWithHeader(src, dest, kind);
+      created.push(basename(dest));
+    }
+  }
+
+  const lines: string[] = [];
+  if (created.length) lines.push("Created:\n  " + created.join("\n  "));
+  if (upgraded.length) lines.push("Upgraded:\n  " + upgraded.join("\n  "));
+  if (unchanged.length) lines.push("Unchanged:\n  " + unchanged.join("\n  "));
+  process.stderr.write((lines.join("\n\n") || "Nothing to do.") + "\n");
+
+  if (created.length || upgraded.length) {
+    process.stderr.write(
+      `\nNext: regenerate your table SQL from types.ts:\n` +
+      `  bunx dzql sql ./types.ts --out ${dir}/003-tables.sql\n`,
+    );
+  }
+}
+
+function compareVersion(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// dzql migrate
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an app's migrations (`--dir`, default ./migrations, each `NNN-name.ts`
+ * exporting `up`; `--app` names the app when apps share the database) against
+ * its database, or with --status say which ran and which are pending. With no
+ * schema to ask, an app with nothing recorded is new only to a database with
+ * no table but delta's: the app's own start-up, given its schema, knows better.
+ * The database: a postgres:// URL or a PGlite directory that is there (a name
+ * mistyped makes no new database). A SQLite file is delta's own command.
+ */
+async function cmdMigrate(target: string | undefined, values: Record<string, unknown>) {
+  if (!target) usageError("migrate takes a <database>: a PGlite directory or a postgres:// URL", true);
+  const { setLogLevel } = await import("@blueshed/delta/logger");
+  setLogLevel(json ? "silent" : "warn");
+  const dir = resolve(process.cwd(), (values.dir as string | undefined) ?? "migrations");
+  const status = !!values.status;
+  const options = { app: (values.app as string | undefined) ?? "" };
+  const isUrl = /^postgres(ql)?:\/\//.test(target);
+  const path = resolve(process.cwd(), target);
+  if (!isUrl && (!existsSync(path) || !statSync(path).isDirectory())) usageError(`no PGlite database at ${target} (a SQLite file is delta's: bunx @blueshed/delta migrate)`);
+  if (!existsSync(dir)) usageError(`no migrations folder at ${dir} (--dir)`);
+
+  let answer: unknown;
+  const pg = await import("./migrate");
+  let pool: any;
+  if (isUrl) {
+    const { Pool } = await import("pg");
+    pool = new Pool({ connectionString: target });
+  } else {
+    const { openPglite } = await import("./pglite");
+    pool = await openPglite(path);
+  }
+  try {
+    const list = await pg.fromFolder(dir);
+    answer = status ? await pg.migrationStatus(pool, list, options) : await pg.migrate(pool, list, options);
+  } finally { await pool.end(); }
+  if (json) return print(answer);
+  if (status) {
+    const s = answer as import("@blueshed/delta/backend").MigrationStatus;
+    if (s.fresh) process.stdout.write("new database: migrate records every migration as run, and runs none\n");
+    for (const r of s.ran) process.stdout.write(`ran      ${r.id}  ${r.ran_at}\n`);
+    for (const id of s.pending) process.stdout.write(`pending  ${id}\n`);
+    for (const id of s.unknown) process.stdout.write(`unknown  ${id}  (ran here, not in ${dir})\n`);
+    return;
+  }
+  const r = answer as import("@blueshed/delta/backend").MigrateResult;
+  if (r.fresh) process.stdout.write("new database: every migration recorded as run, none run\n");
+  for (const id of r.ran) process.stdout.write(`ran      ${id}\n`);
+  if (!r.fresh && r.ran.length === 0) process.stdout.write("nothing to run\n");
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+export async function main(argv: string[]) {
+  let parsed;
+  try { parsed = parseArgs({
+    args: argv,
+    options: {
+      out: { type: "string", short: "o" },
+      force: { type: "boolean", default: false },
+      "schema-export": { type: "string", default: "schema" },
+      "docs-export": { type: "string", default: "docs" },
+      "with-auth": { type: "boolean", default: false },
+      upgrade: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      dir: { type: "string" },
+      app: { type: "string" },
+      status: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+  }); }
+  catch (err) { usageError((err as Error).message, true); }
+  const { values, positionals } = parsed;
+  json = !!values.json;
+  if (values.help) { process.stdout.write(USAGE); return; }
+  const [cmd, arg] = positionals;
+  switch (cmd) {
+    case "sql":     return cmdSql(arg, values);
+    case "init":    return cmdInit(arg, values);
+    case "migrate": return cmdMigrate(arg, values);
+    default:        usageError(cmd ? `no command ${cmd}` : "a command, please", true);
+  }
+}
+
+if (import.meta.main) main(process.argv.slice(2)).catch((err) => fail(err));

package/src/postgres/codegen.ts

@@ -26,6 +26,7 @@ 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";
+import { compileOpens } from "../compile/opens";
 
 export interface GenerateSqlOptions {
   /** Header comment included at the top of the file. */
@@ -168,5 +169,7 @@ export function generateSql(
   }
   lines.push("");
 
+  // each document opened by SQL compiled for it (dzql), which docTypeFromDef calls
+  lines.push("", compileOpens(schema, docs));
   return lines.join("\n");
 }

package/src/postgres/registry.ts

@@ -18,6 +18,7 @@ import type { DocDef } from "./schema";
 import { splitPath, type DeltaOp } from "@blueshed/delta/core";
 import { authless, ownerless, type DeltaAuth } from "@blueshed/delta/auth";
 import { assertOnePrefix } from "@blueshed/delta/backend";
+import { openAtFunction, openFunction } from "../compile/opens";
 
 /** Who is writing, for the ledger: the identity as the ledger has it, and the cursor undo walks. */
 export type Writer = { who: string | null; cursor: string | null; undoable?: boolean; undoes?: number | null };
@@ -214,6 +215,14 @@ export function docTypeFromDef<I = unknown>(
   // owns or shared with no auth module would guard nothing: the listener asks them only with one
   if (!auth && (opts?.owns || opts?.shared)) throw authless(def.prefix, "docTypeFromDef");
 
+  // its reads compiled for it (generateSql), or the framework's for a document registered by hand:
+  // asked until found, then remembered
+  let compiled = false;
+  const reads = async (): Promise<{ open: string; openAt: string }> => {
+    if (!compiled) compiled = (await pool.query("SELECT to_regprocedure($1) IS NOT NULL AS there", [`${openFunction(def.prefix)}(text)`])).rows[0].there;
+    return compiled ? { open: openFunction(def.prefix), openAt: openAtFunction(def.prefix) } : { open: "delta_open", openAt: "delta_open_at" };
+  };
+
   return {
     prefix: def.prefix,
     ...(opts?.owns ? { owns: opts.owns } : {}),
@@ -225,7 +234,7 @@ export function docTypeFromDef<I = unknown>(
     },
 
     async open(_ctx, docName, _msg, identity) {
-      const doc = await callAs(pool, "delta_open", [docName], auth, identity);
+      const doc = await callAs(pool, (await reads()).open, [docName], auth, identity);
       if (!doc) return null;
       const version = doc._version ?? 0;
       delete doc._version;
@@ -247,7 +256,7 @@ export function docTypeFromDef<I = unknown>(
     },
 
     async openAt(_ctx, docName, at, identity) {
-      return (await callAs(pool, "delta_open_at", [docName, at], auth, identity)) ?? null;
+      return (await callAs(pool, (await reads()).openAt, [docName, at], auth, identity)) ?? null;
     },
   };
 }