@facilis.dev/db 0.0.0-stage → 0.1.0

package/src/live-schema.ts

@@ -0,0 +1,145 @@
+import { sql } from "drizzle-orm";
+
+import type { FacilisDb } from "./client.ts";
+import { MIGRATION_TRACKING_TABLE } from "./migrator.ts";
+
+/**
+ * Tables this package owns for its own bookkeeping. They exist in every migrated database
+ * but never in the project schema, so they would otherwise show up as permanent drift.
+ */
+const INTERNAL_TABLES: ReadonlySet<string> = new Set([MIGRATION_TRACKING_TABLE]);
+
+/**
+ * Live database introspection (SPEC §11.1): the catalog side of the code↔live diff.
+ *
+ * Everything here reads Postgres system catalogs, never the Drizzle schema, so the
+ * snapshot describes the database the running project is actually talking to (PGlite in
+ * dev, Postgres in production). Tables are restricted to the connection's current schema:
+ * Facilis projects keep their tables in `public`, and framework-internal schemas such as
+ * `drizzle` must not show up as drift.
+ */
+
+export interface LiveColumnSnapshot {
+  name: string;
+  /** `format_type()` rendering, e.g. `character varying(120)` or `timestamp with time zone`. */
+  type: string;
+  notNull: boolean;
+  default: string | null;
+  isPrimaryKey: boolean;
+}
+
+export interface LivePolicySnapshot {
+  name: string;
+  /** SQL command the policy applies to: ALL, SELECT, INSERT, UPDATE or DELETE. */
+  command: string;
+  /** RESTRICTIVE policies are AND-ed with the permissive ones (D-008). */
+  restrictive: boolean;
+  roles: string[];
+  using: string | null;
+  withCheck: string | null;
+}
+
+export interface LiveTableSnapshot {
+  name: string;
+  rlsEnabled: boolean;
+  columns: LiveColumnSnapshot[];
+  policies: LivePolicySnapshot[];
+}
+
+export interface LiveSchemaSnapshot {
+  tables: LiveTableSnapshot[];
+}
+
+/**
+ * One row per column; table-level attributes (`relrowsecurity`) repeat on every row and
+ * are lifted onto the table when the first column is seen.
+ */
+const COLUMNS_QUERY = sql`
+  select
+    c.relname as table_name,
+    c.relrowsecurity as rls_enabled,
+    a.attname as column_name,
+    format_type(a.atttypid, a.atttypmod) as column_type,
+    a.attnotnull as not_null,
+    pg_get_expr(d.adbin, d.adrelid) as column_default,
+    exists (
+      select 1
+      from pg_index i
+      where i.indrelid = c.oid and i.indisprimary and a.attnum = any (i.indkey)
+    ) as is_primary_key
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+  join pg_attribute a on a.attrelid = c.oid
+  left join pg_attrdef d on d.adrelid = c.oid and d.adnum = a.attnum
+  where n.nspname = current_schema()
+    and c.relkind = 'r'
+    and a.attnum > 0
+    and not a.attisdropped
+  order by c.relname, a.attnum
+`;
+
+/** `pg_policies` is the catalog view over `pg_policy`; it renders each qualifier as SQL. */
+const POLICIES_QUERY = sql`
+  select tablename, policyname, permissive, roles, cmd, qual, with_check
+  from pg_policies
+  where schemaname = current_schema()
+  order by tablename, policyname
+`;
+
+/** Introspect the live database behind a Facilis project. */
+export async function liveSchemaSnapshot(db: FacilisDb): Promise<LiveSchemaSnapshot> {
+  const columnResult = await db.db.execute(COLUMNS_QUERY);
+  const tables = new Map<string, LiveTableSnapshot>();
+  for (const row of columnResult.rows) {
+    const tableName = readText(row, "table_name");
+    const columnName = readText(row, "column_name");
+    if (tableName === null || columnName === null || INTERNAL_TABLES.has(tableName)) continue;
+    const table = tableFor(tables, tableName);
+    table.rlsEnabled = row["rls_enabled"] === true;
+    table.columns.push({
+      name: columnName,
+      type: readText(row, "column_type") ?? "",
+      notNull: row["not_null"] === true,
+      default: readText(row, "column_default"),
+      isPrimaryKey: row["is_primary_key"] === true,
+    });
+  }
+
+  const policyResult = await db.db.execute(POLICIES_QUERY);
+  for (const row of policyResult.rows) {
+    const tableName = readText(row, "tablename");
+    const policyName = readText(row, "policyname");
+    if (tableName === null || policyName === null || INTERNAL_TABLES.has(tableName)) continue;
+    tableFor(tables, tableName).policies.push({
+      name: policyName,
+      command: (readText(row, "cmd") ?? "ALL").toUpperCase(),
+      restrictive: (readText(row, "permissive") ?? "").toUpperCase() === "RESTRICTIVE",
+      roles: readTextArray(row, "roles"),
+      using: readText(row, "qual"),
+      withCheck: readText(row, "with_check"),
+    });
+  }
+
+  return {
+    tables: [...tables.values()].toSorted((left, right) => left.name.localeCompare(right.name)),
+  };
+}
+
+function tableFor(tables: Map<string, LiveTableSnapshot>, name: string): LiveTableSnapshot {
+  const existing = tables.get(name);
+  if (existing !== undefined) return existing;
+  const table: LiveTableSnapshot = { name, rlsEnabled: false, columns: [], policies: [] };
+  tables.set(name, table);
+  return table;
+}
+
+function readText(row: Record<string, unknown>, key: string): string | null {
+  const value = row[key];
+  return typeof value === "string" ? value : null;
+}
+
+function readTextArray(row: Record<string, unknown>, key: string): string[] {
+  const value = row[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string");
+}

package/src/migrator.ts

@@ -0,0 +1,92 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { sql } from "drizzle-orm";
+
+import type { FacilisDb } from "./client.ts";
+
+/** drizzle-kit separates statements in generated SQL files with this marker. */
+const STATEMENT_BREAKPOINT = "--> statement-breakpoint";
+
+/** Bookkeeping table owned by this package, not by the project schema: introspection skips it. */
+export const MIGRATION_TRACKING_TABLE = "_facilis_applied_statements";
+
+export type MigrationSource = string | readonly string[] | { readonly directory: string };
+
+/**
+ * Applies statements in order inside one transaction. Statements are keyed by content
+ * hash and skipped when already applied, so bootstrapping a persistent dataDir twice is
+ * safe; a failure rolls back both the statements and the tracking rows.
+ *
+ * Array entries may either be one SQL statement or a whole file separated by drizzle-kit's
+ * "--> statement-breakpoint" marker (plain semicolons are never used as separators).
+ */
+export async function applyStatements(db: FacilisDb, statements: readonly string[]): Promise<void> {
+  await db.db.transaction(async (tx) => {
+    await tx.execute(
+      sql.raw(
+        `CREATE TABLE IF NOT EXISTS ${MIGRATION_TRACKING_TABLE} (id text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())`,
+      ),
+    );
+
+    for (const statement of statements.flatMap(splitStatementBatch)) {
+      const trimmed = statement.trim();
+      if (trimmed.length === 0) continue;
+
+      // no-await-in-loop: statements must run one at a time on the transaction's connection.
+      // eslint-disable-next-line no-await-in-loop
+      const hashed = await tx.execute(sql`select md5(${trimmed}) as id`);
+      const row = hashed.rows[0];
+      if (row === undefined || typeof row.id !== "string") {
+        throw new Error("applyStatements: failed to hash a migration statement");
+      }
+      const id = row.id;
+
+      // eslint-disable-next-line no-await-in-loop
+      const seen = await tx.execute(
+        sql`select 1 from ${sql.identifier(MIGRATION_TRACKING_TABLE)} where id = ${id}`,
+      );
+      if (seen.rows.length > 0) continue;
+
+      // eslint-disable-next-line no-await-in-loop
+      await tx.execute(sql.raw(trimmed));
+      // eslint-disable-next-line no-await-in-loop
+      await tx.execute(
+        sql`insert into ${sql.identifier(MIGRATION_TRACKING_TABLE)} (id) values (${id})`,
+      );
+    }
+  });
+}
+
+/**
+ * Convenience runner for tests/examples: plain SQL text, a statement list, or a directory
+ * of drizzle-kit `.sql` files (applied in filename order).
+ */
+export async function applyMigrations(db: FacilisDb, source: MigrationSource): Promise<void> {
+  const statements =
+    typeof source === "string"
+      ? [source]
+      : isMigrationDirectory(source)
+        ? readMigrationDirectory(source.directory)
+        : source;
+  await applyStatements(db, statements);
+}
+
+function splitStatementBatch(batch: string): string[] {
+  return batch.split(STATEMENT_BREAKPOINT);
+}
+
+function isMigrationDirectory(
+  source: string | readonly string[] | { readonly directory: string },
+): source is { readonly directory: string } {
+  return typeof source === "object" && "directory" in source;
+}
+
+function readMigrationDirectory(directory: string): string[] {
+  const files = readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".sql"))
+    .map((entry) => entry.name)
+    .toSorted();
+
+  return files.map((file) => readFileSync(join(directory, file), "utf8"));
+}

package/src/policy.ts

@@ -0,0 +1,174 @@
+import { sql } from "drizzle-orm";
+
+import type { FacilisDb, PgDatabaseLike } from "./client.ts";
+
+/** Non-superuser role used for policy-scoped work; RLS is bypassed by superusers (D-008). */
+export const APP_ROLE = "facilis_app";
+
+/** Values exported to Postgres GUCs for one policy-scoped operation (contract §4.2). */
+export interface PolicyScope {
+  readonly tenantId?: string;
+  readonly userId?: string;
+  readonly roles?: readonly string[];
+  /** The session's expanded permissions, read by permission views (D-098). */
+  readonly permissions?: readonly string[];
+}
+
+/** Transaction handed to `runWithPolicyScope` callbacks. */
+export type PolicyScopedTransaction = Parameters<Parameters<PgDatabaseLike["transaction"]>[0]>[0];
+
+/** Drizzle database or transaction accepted by every scoped query helper. */
+export type PolicyScopedDatabase = PgDatabaseLike | PolicyScopedTransaction;
+
+/** Thrown when the app role has not been bootstrapped yet (`ensureAppRole`). */
+export class AppRoleUnavailableError extends Error {
+  readonly code = "app_role_unavailable";
+
+  constructor(cause: unknown) {
+    super(`App role "${APP_ROLE}" is unavailable; run ensureAppRole() after migrations.`, {
+      cause,
+    });
+    this.name = "AppRoleUnavailableError";
+  }
+}
+
+/**
+ * The classification `ensureAppRole` derives from the live schema: every table in `public`
+ * is either RLS-scoped (the app role has DML and the policies decide the rows) or
+ * system-only (no table privilege at all; reachable only through the system identity).
+ * D-136 makes this the invariant: a table without RLS is never app-reachable.
+ */
+export interface AppRoleProvisioning {
+  readonly systemOnlyTables: readonly string[];
+}
+
+/**
+ * Creates the non-superuser role that policy-scoped queries run as and reconciles its
+ * privileges with the live schema: **RLS is the grant boundary** (D-136). A table with RLS
+ * enabled gets DML for the app role (its policies then decide the rows); a table without RLS
+ * gets no table privilege at all, so only the system identity can touch it. Sequences stay
+ * granted to both classes: USAGE can neither read nor write a table, and serial/identity
+ * columns need it for inserts. Idempotent and re-asserting: safe on every boot, and the
+ * blanket grants an older cluster carries are revoked the next time this runs.
+ *
+ * The role is `NOINHERIT` on purpose. It is a member of `facilis_system` so a deployment
+ * whose connection already is `facilis_app` can `SET ROLE` for the audited elevation
+ * (D-099); membership must not hand the request identity the system role's grants, or the
+ * system-only tables would be reachable from every handler. `SET ROLE` still works with
+ * `NOINHERIT`: only implicit inheritance of the member role's privileges is disabled.
+ */
+export async function ensureAppRole(db: FacilisDb): Promise<AppRoleProvisioning> {
+  const existing = await db.db.execute(sql`select 1 from pg_roles where rolname = ${APP_ROLE}`);
+  if (existing.rows.length === 0) {
+    await db.db.execute(
+      sql.raw(`CREATE ROLE ${APP_ROLE} NOLOGIN NOSUPERUSER NOBYPASSRLS NOINHERIT`),
+    );
+  }
+  // Re-assert attributes in case an older dev dataDir created the role differently.
+  await db.db.execute(sql.raw(`ALTER ROLE ${APP_ROLE} NOSUPERUSER NOBYPASSRLS NOLOGIN NOINHERIT`));
+  await db.db.execute(sql.raw(`GRANT USAGE ON SCHEMA public TO ${APP_ROLE}`));
+  // No table default privilege: a table a migration creates stays closed to the app role
+  // until its RLS is on and this function runs again after the migration. The REVOKE also
+  // clears the default an older version of this function installed on existing clusters.
+  await db.db.execute(
+    sql.raw(
+      `ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE SELECT, INSERT, UPDATE, DELETE ON TABLES FROM ${APP_ROLE}`,
+    ),
+  );
+  await db.db.execute(
+    sql.raw(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO ${APP_ROLE}`),
+  );
+  await db.db.execute(
+    sql.raw(
+      `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ${APP_ROLE}`,
+    ),
+  );
+  // Clear every table-class privilege before re-granting: it removes the blanket grant an
+  // older cluster installed on objects the classification below does not cover (partition
+  // children, materialized and foreign tables) and on system-only tables. Views lose their
+  // grant here and get it back from applyViews, the only code that grants one (D-097).
+  await db.db.execute(
+    sql.raw(`REVOKE ALL PRIVILEGES ON ALL TABLES IN SCHEMA public FROM ${APP_ROLE}`),
+  );
+
+  const systemOnlyTables: string[] = [];
+  for (const table of await publicTables(db)) {
+    const identifier = sql.identifier(table.name);
+    if (table.rowSecurityEnabled) {
+      await db.db.execute(
+        sql`grant select, insert, update, delete on table ${identifier} to ${sql.identifier(APP_ROLE)}`,
+      );
+      continue;
+    }
+    // Belt and braces: PUBLIC holds nothing by default, but a hand-written grant must not
+    // reopen a system-only table.
+    await db.db.execute(
+      sql`revoke all privileges on table ${identifier} from ${sql.identifier(APP_ROLE)}`,
+    );
+    await db.db.execute(sql`revoke all privileges on table ${identifier} from public`);
+    systemOnlyTables.push(table.name);
+  }
+  return { systemOnlyTables };
+}
+
+/**
+ * Runs `fn` in one transaction whose Postgres identity is facilis_app and whose GUCs carry
+ * the scope. GUC values travel through set_config parameters, never string concatenation.
+ */
+export async function runWithPolicyScope<T>(
+  db: FacilisDb,
+  scope: PolicyScope,
+  fn: (tx: PolicyScopedDatabase) => Promise<T>,
+): Promise<T> {
+  return db.db.transaction(async (tx) => {
+    try {
+      // SET LOCAL ROLE drops back to the connecting (superuser) role at commit.
+      await tx.execute(sql.raw(`SET LOCAL ROLE ${APP_ROLE}`));
+    } catch (cause) {
+      throw new AppRoleUnavailableError(cause);
+    }
+
+    const roles = JSON.stringify(scope.roles ?? []);
+    const permissions = JSON.stringify(scope.permissions ?? []);
+    await tx.execute(sql`
+      select
+        set_config('app.tenant_id', ${scope.tenantId ?? ""}, true),
+        set_config('app.user_id', ${scope.userId ?? ""}, true),
+        set_config('app.roles', ${roles}, true),
+        set_config('app.permissions', ${permissions}, true)
+    `);
+
+    return fn(tx);
+  });
+}
+
+/** One `public` table, as the catalog reports it (the live schema is the classification). */
+interface PublicTable {
+  readonly name: string;
+  readonly rowSecurityEnabled: boolean;
+}
+
+/**
+ * The grant loop's input. The catalog, not the code schema, decides: migrations are what
+ * actually enabled RLS. Partition children are skipped — routing through a partitioned
+ * parent checks the parent's privilege, and the framework has no partitioned tables today.
+ */
+async function publicTables(db: FacilisDb): Promise<PublicTable[]> {
+  const result = await db.db.execute(sql`
+    select c.relname as name, c.relrowsecurity as row_security
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'public' and c.relkind in ('r', 'p') and not c.relispartition
+    order by c.relname
+  `);
+  const tables: PublicTable[] = [];
+  for (const row of result.rows) {
+    const name = row["name"];
+    const rowSecurityEnabled = row["row_security"];
+    if (typeof name !== "string" || typeof rowSecurityEnabled !== "boolean") {
+      throw new Error("ensureAppRole: unexpected pg_class row shape");
+    }
+    tables.push({ name, rowSecurityEnabled });
+  }
+  return tables;
+}

package/src/query-console.ts

@@ -0,0 +1,215 @@
+// Read-only SQL execution and live view creation for the Studio's dev console
+// (SPEC §11.2, D-097).
+//
+// This lives in @facilis.dev/db because it is SQL: AGENTS.md security rule 5 keeps raw Drizzle
+// imports inside this package. The Nitro route owns transport and validation; this module
+// owns the read-only transaction and the JSON-safe result shape.
+
+import { sql } from "drizzle-orm";
+
+import type { FacilisDb } from "./client.ts";
+import { APP_ROLE } from "./policy.ts";
+import { isReadOnlySql, stripTrailingSemicolon } from "./read-only-sql.ts";
+import { grantViewSelect, ViewDefinitionError, viewDefinitionStatement } from "./views.ts";
+
+export const DEFAULT_QUERY_LIMIT = 100;
+export const MAX_QUERY_LIMIT = 500;
+/** A console query must not hang the dev server; 5s is generous for a preview. */
+export const QUERY_STATEMENT_TIMEOUT_MS = 5000;
+
+export type QueryExecutionErrorCode =
+  "invalid_name" | "invalid_sql" | "invalid_permission" | "query_failed" | "create_failed";
+
+/** A console operation the route reports as a 400 `{ code }` body. */
+export class QueryExecutionError extends Error {
+  readonly code: QueryExecutionErrorCode;
+
+  constructor(code: QueryExecutionErrorCode, message: string) {
+    super(message);
+    this.name = "QueryExecutionError";
+    this.code = code;
+  }
+}
+
+export interface QueryColumn {
+  readonly name: string;
+  /** Postgres type name from pg_type (e.g. "uuid", "timestamptz"). */
+  readonly pgType: string;
+}
+
+export interface QueryExecution {
+  readonly columns: readonly QueryColumn[];
+  readonly rows: readonly (readonly unknown[])[];
+  readonly rowCount: number;
+  readonly elapsedMs: number;
+  readonly truncated: boolean;
+}
+
+interface PgliteField {
+  readonly name: string;
+  readonly dataTypeID: number;
+}
+
+/**
+ * Run one read-only statement for the console.
+ *
+ * The prefix check is the friendly error; the read-only transaction is the boundary: a
+ * data-modifying CTE (WITH ... DELETE) passes the prefix check and is rejected by
+ * Postgres. The statement is wrapped in an outer LIMIT so a preview cannot stream the
+ * whole table into the browser, and a statement timeout keeps a runaway query from
+ * pinning the dev server.
+ */
+export async function runReadOnlyQuery(
+  db: FacilisDb,
+  sqlText: string,
+  limit = DEFAULT_QUERY_LIMIT,
+): Promise<QueryExecution> {
+  if (!isReadOnlySql(sqlText)) {
+    throw new QueryExecutionError(
+      "invalid_sql",
+      "The console runs one read-only statement (SELECT, WITH, VALUES or TABLE).",
+    );
+  }
+  const statement = stripTrailingSemicolon(sqlText);
+  const capped = Math.min(Math.max(Math.trunc(limit), 1), MAX_QUERY_LIMIT);
+  const startedAt = performance.now();
+
+  try {
+    return await db.db.transaction(async (tx) => {
+      await tx.execute(sql.raw("set transaction read only"));
+      await tx.execute(
+        sql.raw("set local statement_timeout = '" + QUERY_STATEMENT_TIMEOUT_MS + "ms'"),
+      );
+      const result = await tx.execute(
+        sql.raw("select * from (\n" + statement + "\n) as __facilis_query limit " + (capped + 1)),
+      );
+      const fields = readFields(result);
+      if (fields.length === 0) {
+        throw new QueryExecutionError("query_failed", "The statement returned no result columns.");
+      }
+      const types = await readTypeNames(tx, fields);
+      const rows = result.rows
+        .slice(0, capped)
+        .map((row) => fields.map((field) => toJsonValue(row[field.name])));
+      return {
+        columns: fields.map((field) => ({
+          name: field.name,
+          pgType: types.get(field.dataTypeID) ?? "unknown",
+        })),
+        rows,
+        rowCount: rows.length,
+        elapsedMs: Math.round(performance.now() - startedAt),
+        truncated: result.rows.length > capped,
+      };
+    });
+  } catch (error) {
+    // Postgres errors are plain driver objects; the console reports the reason as a code,
+    // never a 500 with a stack.
+    if (error instanceof QueryExecutionError) throw error;
+    throw new QueryExecutionError("query_failed", messageOf(error));
+  }
+}
+
+/**
+ * Create (or replace) a live view from the console's SQL and grant the policy role.
+ * The Studio writes db/views/<name>.ts afterwards; this call makes the view usable
+ * immediately, before the next boot re-applies the code.
+ */
+export async function createLiveView(
+  db: FacilisDb,
+  name: string,
+  queryText: string,
+  permission?: string,
+): Promise<void> {
+  let statement;
+  try {
+    statement = viewDefinitionStatement(name, queryText, permission);
+  } catch (error) {
+    if (error instanceof ViewDefinitionError) {
+      throw new QueryExecutionError(error.code, error.message);
+    }
+    throw error;
+  }
+  try {
+    await db.db.execute(statement);
+  } catch (error) {
+    throw new QueryExecutionError("create_failed", messageOf(error));
+  }
+  try {
+    await grantViewSelect(db, name);
+  } catch (error) {
+    throw new QueryExecutionError(
+      "create_failed",
+      "View created, but the grant to " + APP_ROLE + " failed: " + messageOf(error),
+    );
+  }
+}
+
+async function readTypeNames(
+  tx: { execute(query: ReturnType<typeof sql.raw>): Promise<{ rows: Record<string, unknown>[] }> },
+  fields: readonly PgliteField[],
+): Promise<Map<number, string>> {
+  const types = new Map<number, string>();
+  const oids = [...new Set(fields.map((field) => field.dataTypeID))].filter((oid) =>
+    Number.isInteger(oid),
+  );
+  if (oids.length === 0) return types;
+  const result = await tx.execute(
+    sql.raw("select oid, typname from pg_type where oid in (" + oids.join(", ") + ")"),
+  );
+  for (const row of result.rows) {
+    const oid = Number(row["oid"]);
+    const name = row["typname"];
+    if (Number.isInteger(oid) && typeof name === "string") types.set(oid, name);
+  }
+  return types;
+}
+
+function readFields(result: unknown): PgliteField[] {
+  if (typeof result !== "object" || result === null) return [];
+  const fields = Reflect.get(result, "fields");
+  if (!Array.isArray(fields)) return [];
+  const out: PgliteField[] = [];
+  for (const entry of fields) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const name = Reflect.get(entry, "name");
+    const oid = Reflect.get(entry, "dataTypeID");
+    if (typeof name === "string" && typeof oid === "number") out.push({ name, dataTypeID: oid });
+  }
+  return out;
+}
+
+/**
+ * JSON-safe cell value. Postgres drivers hand back bigint, Date, Uint8Array and nested
+ * jsonb; JSON.stringify would throw on bigint and silently reshape the rest.
+ */
+export function toJsonValue(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Uint8Array) return "\\x" + [...value].map(hexByte).join("");
+  if (Array.isArray(value)) return value.map(toJsonValue);
+  if (typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) out[key] = toJsonValue(entry);
+    return out;
+  }
+  return String(value);
+}
+
+function hexByte(byte: number): string {
+  return byte.toString(16).padStart(2, "0");
+}
+
+function messageOf(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  // Drizzle wraps a driver error in "Failed query: …"; the reason (e.g. "cannot execute
+  // DELETE in a read-only transaction") is in the cause and is what the console shows.
+  const cause = error.cause;
+  if (cause instanceof Error && cause.message.length > 0) {
+    return error.message + ": " + cause.message;
+  }
+  return error.message;
+}