@ultimat3/db 1.0.0

package/src/pglite.ts

@@ -0,0 +1,200 @@
+// Single responsibility: the embedded development database — Postgres compiled to WASM, running
+// inside this process, so `x dev` needs no Docker, no DATABASE_URL and no container to wait for.
+// The module is resolved at first query and never at import: it is an OPTIONAL peer, and an image
+// that only ever talks to a managed Postgres must not carry 26 MB of WASM it will never load.
+
+import type { DbConnection, ReservableClient } from './client';
+import { DbError, dbUnavailable } from './errors';
+import { createTurnQueue } from './pglite-turns';
+import type { SqlFragment } from './sql';
+import { currentTx } from './transaction';
+
+/** What PGlite answers with. `rows` is empty for a write, which is why the count is separate. */
+export interface PgliteResult {
+  readonly rows: readonly unknown[];
+  /** Postgres' command-tag count — the only truthful answer for INSERT/UPDATE/DELETE. */
+  readonly affectedRows?: number | undefined;
+}
+
+/** The slice of PGlite we need. Declared structurally — this package has no dependencies. */
+export interface PgliteDriver {
+  query(text: string, values?: readonly unknown[]): Promise<PgliteResult>;
+  exec?(text: string): Promise<unknown>;
+  close(): Promise<void>;
+}
+
+/** The one export taken off `@electric-sql/pglite`. */
+export interface PgliteModule {
+  readonly PGlite: new (dataDir?: string) => PgliteDriver;
+}
+
+/** Returns the module namespace. Unknown, not typed, because it is validated before use. */
+export type PgliteLoader = () => Promise<unknown>;
+
+export interface PgliteOptions {
+  /** `memory://` (default) or a directory. Branches are a directory per branch. */
+  readonly dataDir?: string | undefined;
+  /** Inject a driver — tests do this so no test needs the WASM build. */
+  readonly driver?: PgliteDriver | undefined;
+  /** Swap the module loader. Tests use it; nothing in the framework does. */
+  readonly load?: PgliteLoader | undefined;
+}
+
+export const PGLITE_FIX =
+  'bun add @electric-sql/pglite, or set DATABASE_URL to a Postgres server and re-run';
+
+/** Postgres with no filesystem behind it: the default, and what a test wants. */
+export const PGLITE_MEMORY = 'memory://';
+
+const PGLITE_URL = 'pglite://';
+
+const PGLITE_PACKAGE = '@electric-sql/pglite';
+
+/**
+ * The specifier is held in a variable on purpose: a literal would make every consumer's `tsc`
+ * resolve an optional peer that is legitimately absent, and every bundler inline it.
+ */
+const importPglite: PgliteLoader = () => import(PGLITE_PACKAGE);
+
+const missing = (cause: string, sourceError?: unknown): DbError =>
+  new DbError({ code: 'X_DB_UNAVAILABLE', cause, fix: PGLITE_FIX, sourceError });
+
+/**
+ * `pglite://<dir>` and `pglite://memory/<name>` — the URLs `x dev` and the test template already
+ * print — read back as the dataDir the driver takes. One parser, so no caller invents a second.
+ */
+export function pgliteDataDir(url: string): string {
+  if (!url.startsWith(PGLITE_URL)) return url;
+  const rest = url.slice(PGLITE_URL.length);
+  return rest === '' || rest === 'memory' || rest.startsWith('memory/') ? PGLITE_MEMORY : rest;
+}
+
+function pgliteConstructor(loaded: unknown): PgliteModule['PGlite'] {
+  const exported = (loaded as { readonly PGlite?: unknown } | null | undefined)?.PGlite;
+  if (typeof exported !== 'function') {
+    throw missing(`${PGLITE_PACKAGE} resolved but exports no PGlite constructor`);
+  }
+  return exported as PgliteModule['PGlite'];
+}
+
+/** Boots one embedded Postgres. Costs seconds — `createPgliteClient` calls it exactly once. */
+export async function loadPgliteDriver(options: PgliteOptions = {}): Promise<PgliteDriver> {
+  if (options.driver !== undefined) return options.driver;
+  const dataDir = options.dataDir ?? PGLITE_MEMORY;
+  let loaded: unknown;
+  try {
+    loaded = await (options.load ?? importPglite)();
+  } catch (error) {
+    throw missing(`${PGLITE_PACKAGE} is not installed, so there is no embedded database`, error);
+  }
+  const PGlite = pgliteConstructor(loaded);
+  try {
+    return new PGlite(dataDir);
+  } catch (error) {
+    throw missing(`PGlite could not open its data directory (dataDir=${dataDir})`, error);
+  }
+}
+
+/**
+ * Reservable, and that is the whole point of the binding: `withTransaction` and `readOnlyQuery`
+ * both pin a connection before they `BEGIN`, and a client that cannot be pinned silently gets a
+ * shared one — which on a single-session database is every concurrent transaction at once.
+ */
+export interface PgliteClient extends ReservableClient {
+  /** Pay the boot up front. `x dev` calls it so the first request is not the slow one. */
+  ping(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Lazily boots: constructing a client opens nothing, exactly like `createPostgresClient`. */
+export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
+  // One in-flight boot, shared. PGlite takes seconds to start, so two concurrent first queries
+  // would otherwise build two instances over the same data directory and orphan one of them.
+  let booting: Promise<PgliteDriver> | undefined;
+  const turns = createTurnQueue();
+
+  function connect(): Promise<PgliteDriver> {
+    booting ??= loadPgliteDriver(options).catch((error: unknown) => {
+      // A failed boot must not be cached: the fix is `bun add`, and then this has to work.
+      booting = undefined;
+      throw error;
+    });
+    return booting;
+  }
+
+  async function statement(driver: PgliteDriver, fragment: SqlFragment): Promise<PgliteResult> {
+    try {
+      return await driver.query(fragment.text, fragment.values);
+    } catch (error) {
+      throw dbUnavailable(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+    }
+  }
+
+  async function run(fragment: SqlFragment): Promise<PgliteResult> {
+    const driver = await connect();
+    // A statement issued inside an open transaction is already inside it — there is one
+    // connection and that transaction is holding the turn, so waiting for a turn we are already
+    // inside of would hang. `handle.enqueue(input, { outbox: false })` within `withTransaction`
+    // is the shape that reaches this line; on a pooled server it would get its own connection,
+    // and here it joins the caller's transaction because a second connection does not exist.
+    if (currentTx() !== undefined) return statement(driver, fragment);
+    return turns.run(() => statement(driver, fragment));
+  }
+
+  // PGlite counts MODIFIED rows, so a SELECT that returned rows still reports `affectedRows: 0` —
+  // `??` would answer 0 for every read and disagree with `PostgresClient.execute`. A write that
+  // modified nothing returned no rows either, so falling back to the row count stays 0 there.
+  const rowsOf = (result: PgliteResult): number =>
+    result.affectedRows !== undefined && result.affectedRows > 0
+      ? result.affectedRows
+      : result.rows.length;
+
+  return {
+    async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
+      return (await run(fragment)).rows as readonly T[];
+    },
+    async one<T>(fragment: SqlFragment): Promise<T | null> {
+      const { rows } = await run(fragment);
+      return (rows[0] as T | undefined) ?? null;
+    },
+    async execute(fragment: SqlFragment): Promise<number> {
+      return rowsOf(await run(fragment));
+    },
+    async reserve(): Promise<DbConnection> {
+      const driver = await connect();
+      // Held until `release()`, so every statement between `BEGIN` and `COMMIT` is this caller's
+      // and no other unit of work can interleave one of its own.
+      const turn = await turns.take();
+      let held = true;
+      // Direct only while the turn is held — re-queueing behind ourselves would deadlock. Once
+      // released the handle has no claim on the connection, and a leaked `tx` writing straight to
+      // it would land inside whatever transaction holds it now, with no error to read; so a late
+      // statement queues like any other caller and waits for its own turn.
+      const on = (fragment: SqlFragment): Promise<PgliteResult> =>
+        held ? statement(driver, fragment) : turns.run(() => statement(driver, fragment));
+      return {
+        query: async <T>(fragment: SqlFragment) => (await on(fragment)).rows as readonly T[],
+        one: async <T>(fragment: SqlFragment) =>
+          ((await on(fragment)).rows[0] as T | undefined) ?? null,
+        execute: async (fragment: SqlFragment) => rowsOf(await on(fragment)),
+        release: () => {
+          held = false;
+          turn();
+        },
+      };
+    },
+    async ping(): Promise<void> {
+      await connect();
+    },
+    async close(): Promise<void> {
+      const pending = booting;
+      booting = undefined;
+      // A boot that never finished has nothing to close, and re-throwing its failure here would
+      // mask whatever the process was actually shutting down for.
+      await pending?.then(
+        (driver) => driver.close(),
+        () => undefined,
+      );
+    },
+  };
+}

package/src/readonly-query.ts

@@ -0,0 +1,155 @@
+// Single responsibility: LAYER 2 of `db.query`'s defence-in-depth — an isolated `BEGIN READ
+// ONLY` transaction with a statement timeout for any SQL an LLM is about to run. Postgres
+// enforcing read-only beats a regex, and the timeout bounds a runaway scan the agent never
+// meant to ask for.
+
+import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
+import { stripSqlNoise } from './readonly';
+import { identifier, raw, sql } from './sql';
+
+/** Default per-statement ceiling for an agent-authored read. */
+export const READONLY_TIMEOUT_MS = 5_000;
+
+/**
+ * Leaders Postgres accepts in `DECLARE ... CURSOR FOR`. `EXPLAIN` and `SHOW` are commands, not
+ * queries, so they have no cursor form and stay on the direct path.
+ */
+const CURSORABLE_LEADERS = new Set(['select', 'with', 'table', 'values']);
+
+/** Fixed: the cursor lives inside one pinned transaction that always rolls back. */
+const CURSOR_NAME = 'ultimate_read_cursor';
+
+export interface ReadOnlyQueryOptions {
+  /** Override the ambient pool. */
+  readonly client?: DbClient | undefined;
+  /** Role to assume for the statement, from `ensureReadOnlyRole`. `null` = none available. */
+  readonly role?: string | null | undefined;
+  /** 0 disables. Default READONLY_TIMEOUT_MS. */
+  readonly timeoutMs?: number | undefined;
+  /**
+   * Ask the server for at most this many rows, through a cursor. A caller that slices the
+   * answer afterwards has already paid for every row the driver produced — `select * from
+   * events` materialises the whole table in this process before any ceiling gets to drop it,
+   * and a statement timeout does not stop a fast scan that simply returns a lot. Omit for the
+   * whole result set. Ignored for `EXPLAIN`/`SHOW`, which have no cursor form.
+   */
+  readonly maxRows?: number | undefined;
+}
+
+export interface ReadOnlyQueryResult<T> {
+  readonly rows: readonly T[];
+  /** The defences that actually engaged, in the order they ran. Reported, never assumed. */
+  readonly guards: readonly string[];
+}
+
+/**
+ * A whole positive row count, or `undefined` when the caller wants everything. NaN and a
+ * fractional or negative ask are the same mistake — treat them as "no cursor" rather than
+ * emitting `FETCH FORWARD NaN`, which Postgres would reject as a syntax error.
+ */
+function fetchCount(maxRows: number | undefined): number | undefined {
+  if (maxRows === undefined || !Number.isFinite(maxRows)) return undefined;
+  const whole = Math.trunc(maxRows);
+  return whole > 0 ? whole : undefined;
+}
+
+/**
+ * True when Postgres will accept `statement` as a cursor's query. Reads the leading keyword off
+ * the *stripped* form so a leading comment or a keyword inside a literal cannot decide it.
+ */
+function cursorable(statement: string): boolean {
+  const leader = /^\s*([a-z]+)/i.exec(stripSqlNoise(statement))?.[1]?.toLowerCase();
+  return leader !== undefined && CURSORABLE_LEADERS.has(leader);
+}
+
+/**
+ * Runs `statement` inside its own `BEGIN READ ONLY` transaction, on one pinned connection, and
+ * always exits via `ROLLBACK` — a read-only transaction has nothing to commit, and rollback is
+ * the one exit that cannot be wrong. The statement has already been parsed and accepted
+ * upstream, so this does not re-scan it for mutating keywords: a second gate is a second place
+ * to keep right.
+ *
+ * Deliberately does not use `withTransaction`: it nests into an ambient transaction with a
+ * `SAVEPOINT`, and a savepoint inside a read-write transaction is not read-only. Deliberately
+ * does not wrap the connection in `readOnly()` either: that guard's regex would refuse our own
+ * `SET LOCAL` statements, and `BEGIN READ ONLY` is a stronger, Postgres-enforced backstop.
+ */
+export async function readOnlyQuery<T>(
+  statement: string,
+  options: ReadOnlyQueryOptions = {},
+): Promise<ReadOnlyQueryResult<T>> {
+  const client = options.client ?? baseClient();
+  // A pooled BEGIN that lands on a different physical connection than the query that follows is
+  // not a transaction at all, so a reservable client must pin one connection for the sequence.
+  const reserved: DbConnection | undefined = isReservable(client)
+    ? await client.reserve()
+    : undefined;
+  const connection: DbClient = reserved ?? client;
+  const guards: string[] = [];
+
+  try {
+    await connection.execute(raw('BEGIN READ ONLY'));
+    guards.push('txn:read-only');
+
+    // Clamped and truncated to an integer: the result is a JS number the caller never touches
+    // as text, so there is nothing here for `raw()` to inject — `SET LOCAL` can't bind `$n`
+    // parameters, which is why this can't go through `sql` the normal, parameterised way.
+    // NaN normalises to the default first: only an explicit 0 disables the timeout, and
+    // `Math.min(3_600_000, NaN)` is NaN, which would fail `ms > 0` and silently skip the layer.
+    const asked = options.timeoutMs ?? READONLY_TIMEOUT_MS;
+    const requested = Number.isNaN(asked) ? READONLY_TIMEOUT_MS : asked;
+    const ms = Math.max(0, Math.min(3_600_000, Math.trunc(requested)));
+    if (ms > 0) {
+      // `LOCAL`, so the setting dies with the transaction — one agent read must not re-time
+      // every request the pool serves afterwards. Caveat: embedded PGlite applies the setting
+      // but is single-threaded WASM, so it cannot interrupt a running scan; on a real server
+      // the timeout fires. Layers 1 and 3 do not depend on it.
+      await connection.execute(raw(`SET LOCAL statement_timeout = ${ms}`));
+      guards.push(`timeout:${ms}ms`);
+    }
+
+    // Timeout first, then role: a role restricted to SELECT must not be the one asked to change
+    // the session's own statement_timeout.
+    if (typeof options.role === 'string' && options.role.length > 0) {
+      await connection.execute(sql`SET LOCAL ROLE ${identifier(options.role)}`);
+      guards.push(`role:${options.role}`);
+    }
+
+    const rows = await readRows<T>(connection, statement, fetchCount(options.maxRows), guards);
+    await connection.execute(raw('ROLLBACK'));
+    return { rows, guards };
+  } catch (error) {
+    // Best-effort: the caller needs the original error, never the rollback's.
+    await connection.execute(raw('ROLLBACK')).catch(() => undefined);
+    throw error;
+  } finally {
+    reserved?.release();
+  }
+}
+
+/**
+ * Run the caller's statement and return its rows, bounded at the server when it can be.
+ *
+ * `DECLARE ... CURSOR` costs one extra round trip and buys the only bound that exists before the
+ * rows are in this process: without it `maxRows` describes what the caller *keeps*, not what the
+ * driver *allocates*. `NO SCROLL` because nothing here reads backwards, and the cursor needs no
+ * closing — it dies with the transaction that always rolls back.
+ *
+ * The statement is spliced in, not bound: a cursor's query is syntax, and there is no `$n` that
+ * could carry it. It has already passed the caller's own gate — this function adds no second one.
+ */
+async function readRows<T>(
+  connection: DbClient,
+  statement: string,
+  fetch: number | undefined,
+  guards: string[],
+): Promise<readonly T[]> {
+  if (fetch === undefined || !cursorable(statement)) return connection.query<T>(raw(statement));
+
+  // A trailing `;` would close `DECLARE` before its query and turn one statement into two.
+  const query = statement.trim().replace(/;\s*$/, '');
+  await connection.execute(raw(`DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${query}`));
+  const rows = await connection.query<T>(raw(`FETCH FORWARD ${fetch} FROM ${CURSOR_NAME}`));
+  guards.push(`fetch:${fetch} rows`);
+  return rows;
+}

package/src/readonly-role.ts

@@ -0,0 +1,116 @@
+// Single responsibility: LAYER 1 of `db.query`'s defence-in-depth — a Postgres role that can
+// only SELECT. A grant set is the layer that survives a bug in every other layer, because
+// Postgres itself refuses the write. `NOLOGIN` means it is reachable only via `SET LOCAL ROLE`
+// inside an already-`READ ONLY` transaction, never by a connection string.
+
+import type { DbClient } from './client';
+import { identifier, literal, raw, type SqlFragment, sql } from './sql';
+
+/** The role `ensureReadOnlyRole` creates and `readOnlyQuery` assumes by default. */
+export const READONLY_ROLE = 'ultimate_readonly';
+
+export interface ReadOnlyRoleOptions {
+  readonly role?: string | undefined;
+  readonly schema?: string | undefined;
+  /**
+   * The roles that CREATE objects in `schema` — in practice whoever runs the migrations.
+   * Postgres scopes `ALTER DEFAULT PRIVILEGES` to objects created by the roles it names, so when
+   * migrations run as a different user than this DDL, every table created afterwards is
+   * unreadable by the read-only role and layer 1 quietly stops covering new tables. Defaults to
+   * the connected user; naming another role requires membership in it.
+   */
+  readonly creators?: readonly string[] | undefined;
+}
+
+/**
+ * `CURRENT_USER` is a keyword, not an identifier — quoting it would name a role actually called
+ * "current_user", so it stays bare exactly like `GRANT ... TO CURRENT_USER` below.
+ */
+function creatorRefs(creators: readonly string[] | undefined): readonly SqlFragment[] {
+  // Absent *or* empty means "whoever is connected", never "no creators": the second reading would
+  // silently drop the layer for every object created after this DDL.
+  if (creators === undefined || creators.length === 0) return [raw('CURRENT_USER')];
+  return creators.map((creator) => identifier(creator));
+}
+
+/**
+ * Emitted once per creating role, because Postgres applies `ALTER DEFAULT PRIVILEGES` only to
+ * objects created by the roles it names. Without the pair its own defaults work against us: a
+ * table created after this DDL is invisible to SELECT while a new sequence is readable —
+ * backwards for a role that must stay read-only forever, not just at grant time.
+ */
+function defaultPrivileges(
+  creator: SqlFragment,
+  role: string,
+  schema: string,
+): readonly SqlFragment[] {
+  return [
+    sql`
+      ALTER DEFAULT PRIVILEGES FOR ROLE ${creator} IN SCHEMA ${identifier(schema)}
+      GRANT SELECT ON TABLES TO ${identifier(role)}
+    `,
+    sql`
+      ALTER DEFAULT PRIVILEGES FOR ROLE ${creator} IN SCHEMA ${identifier(schema)}
+      REVOKE ALL ON SEQUENCES FROM ${identifier(role)}
+    `,
+  ];
+}
+
+/** The idempotent DDL that creates and re-grants the role. Safe to run at every boot. */
+export function grantReadOnlySql(options?: ReadOnlyRoleOptions): readonly SqlFragment[] {
+  const role = options?.role ?? READONLY_ROLE;
+  const schema = options?.schema ?? 'public';
+
+  return [
+    // `CREATE ROLE` has no `IF NOT EXISTS`, so the guard is a DO block. The name is compared as
+    // a string literal (`literal()`) in the check and quoted as an identifier (`identifier()`)
+    // where it names the role — never spliced in as bare text either way.
+    sql`
+      DO $ultimate$
+      BEGIN
+        IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = ${literal(role)}) THEN
+          CREATE ROLE ${identifier(role)} NOLOGIN NOINHERIT;
+        END IF;
+      END $ultimate$
+    `,
+    // NOLOGIN roles are only usable by their members, so the connected user needs membership
+    // before it can ever `SET LOCAL ROLE` into this one.
+    sql`GRANT ${identifier(role)} TO CURRENT_USER`,
+    sql`GRANT USAGE ON SCHEMA ${identifier(schema)} TO ${identifier(role)}`,
+    sql`GRANT SELECT ON ALL TABLES IN SCHEMA ${identifier(schema)} TO ${identifier(role)}`,
+    // Sequences expose nextval/currval, which leaks row counts and (with USAGE) lets a "reader"
+    // advance state other transactions depend on — read-only excludes them outright.
+    sql`REVOKE ALL ON ALL SEQUENCES IN SCHEMA ${identifier(schema)} FROM ${identifier(role)}`,
+    // Two per creating role: what the grants above cover is the schema as it is *now*, and
+    // `ALTER DEFAULT PRIVILEGES` is the only thing that covers what lands in it next.
+    ...creatorRefs(options?.creators).flatMap((creator) =>
+      defaultPrivileges(creator, role, schema),
+    ),
+  ];
+}
+
+/**
+ * Create/refresh the role and make it assumable by the current user.
+ *
+ * Returns the role name when the role exists and may be assumed, `null` when the connection is
+ * not allowed to create or grant roles (a managed Postgres where the app user is not a role
+ * admin). Never throws: the other three layers still hold without this one, and the caller
+ * reports the missing layer instead of losing all four to an exception.
+ */
+export async function ensureReadOnlyRole(
+  client: DbClient,
+  options?: ReadOnlyRoleOptions,
+): Promise<string | null> {
+  const role = options?.role ?? READONLY_ROLE;
+  try {
+    for (const statement of grantReadOnlySql(options)) {
+      await client.execute(statement);
+    }
+    return role;
+  } catch {
+    // Swallowed deliberately: a managed Postgres often refuses CREATE ROLE / GRANT to the app
+    // user. The other three layers (read-only transaction, statement timeout, pre-parse scan)
+    // still hold — the caller reports this layer as degraded rather than the boot crashing.
+    return null;
+  }
+}

package/src/readonly.ts

@@ -0,0 +1,111 @@
+// Single responsibility: a `DbClient` that cannot mutate — for any caller that cannot open its
+// own transaction. An LLM with a Postgres connection and no gate is an outage waiting to be
+// prompted into existence. (MCP's `db.query` reaches past this for the stronger `readOnlyQuery`:
+// a SELECT-only role inside `BEGIN READ ONLY`, where Postgres refuses the write, not a regex.)
+// Detection strips comments and string literals first, because
+// `/* x */ update ...` and `WITH t AS (INSERT ...) SELECT` are exactly how a naive check is beaten.
+
+import type { DbClient } from './client';
+import { readonlyViolation } from './errors';
+import { raw, type SqlFragment } from './sql';
+
+const MUTATING = [
+  'insert',
+  'update',
+  'delete',
+  'truncate',
+  'drop',
+  'alter',
+  'create',
+  'grant',
+  'revoke',
+  'copy',
+  'set',
+  'call',
+  'do',
+  'refresh',
+  'vacuum',
+  'reindex',
+  'cluster',
+  'lock',
+  'merge',
+  'analyze',
+  'prepare',
+  'execute',
+] as const;
+
+const MUTATING_PATTERN = new RegExp(`\\b(${MUTATING.join('|')})\\b`, 'i');
+
+/**
+ * Blank out anything a keyword could legitimately hide inside: line comments, block comments,
+ * single-quoted literals, dollar-quoted bodies and quoted identifiers. Blanking (rather than
+ * deleting) keeps offsets stable so the reported statement still reads correctly.
+ */
+export function stripSqlNoise(text: string): string {
+  return text
+    .replace(/\$([A-Za-z_]\w*)?\$[\s\S]*?\$\1?\$/g, ' ')
+    .replace(/--[^\n]*/g, ' ')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/'(?:[^']|'')*'/g, " '' ")
+    .replace(/"(?:[^"]|"")*"/g, ' "" ');
+}
+
+export interface MutationVerdict {
+  readonly mutating: boolean;
+  readonly keyword: string | null;
+}
+
+/**
+ * Whole-text scan, not a leading-keyword check: multi-statement strings and CTEs that end in a
+ * writing branch must both be caught, and a false positive here is far cheaper than a false
+ * negative. `updated_at` and `offset` do not match — `\b` requires a non-word boundary.
+ */
+export function inspectStatement(text: string): MutationVerdict {
+  const match = MUTATING_PATTERN.exec(stripSqlNoise(text));
+  if (match === null) return { mutating: false, keyword: null };
+  return { mutating: true, keyword: match[1] ?? match[0] };
+}
+
+export function assertReadOnly(fragment: SqlFragment): void {
+  const verdict = inspectStatement(fragment.text);
+  if (!verdict.mutating) return;
+  throw readonlyViolation(fragment.text.trim().slice(0, 160), verdict.keyword ?? 'mutating');
+}
+
+export interface ReadOnlyOptions {
+  /** Also ask Postgres to enforce it. Off only for clients that cannot run `SET TRANSACTION`. */
+  readonly seal?: boolean | undefined;
+}
+
+/**
+ * Belt and braces: the regex is the gate, `SET TRANSACTION READ ONLY` is the backstop for
+ * anything the regex was too clever to catch. Sealing is best-effort — outside a transaction
+ * block Postgres only warns, and a driver that rejects it must not break every read.
+ */
+export function readOnly(client: DbClient, options: ReadOnlyOptions = {}): DbClient {
+  let sealed = options.seal === false;
+
+  async function seal(): Promise<void> {
+    if (sealed) return;
+    sealed = true;
+    await client.execute(raw('SET TRANSACTION READ ONLY')).catch(() => undefined);
+  }
+
+  return {
+    async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
+      assertReadOnly(fragment);
+      await seal();
+      return client.query<T>(fragment);
+    },
+    async one<T>(fragment: SqlFragment): Promise<T | null> {
+      assertReadOnly(fragment);
+      await seal();
+      return client.one<T>(fragment);
+    },
+    async execute(fragment: SqlFragment): Promise<number> {
+      assertReadOnly(fragment);
+      await seal();
+      return client.execute(fragment);
+    },
+  };
+}