cairnq 0.8.0 → 0.9.0

package/dist/store/sqlite.js

@@ -1,9 +1,27 @@
 import { mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import Database from "better-sqlite3";
+import { createRequire } from "node:module";
 import { nowMs } from "../ids.js";
 import { loadMigrations, loadStatements } from "../sql.js";
 import { checkProtocolVersion, COMMENT, statementParams, TaskStore, } from "./base.js";
+// `better-sqlite3` is an optional dependency, matching `pg` on the Postgres side:
+// a Postgres-only deployment should not have to build a native module it never
+// loads, and importing this file must not pull one in. Required (not imported)
+// because ensure() is synchronous — the open path applies migrations and cannot
+// await — and createRequire gives a synchronous load from ESM.
+const require = createRequire(import.meta.url);
+let sqliteModule = null;
+function loadSqlite() {
+    if (sqliteModule)
+        return sqliteModule;
+    try {
+        sqliteModule = require("better-sqlite3");
+    }
+    catch {
+        throw new Error("SQLiteStore requires the 'better-sqlite3' package — install it (e.g. `npm i better-sqlite3`)");
+    }
+    return sqliteModule;
+}
 const WAL_RETRY_DELAY_MS = 50;
 const WAL_RETRY_BUDGET_MS = 5_000;
 const BUSY_RETRY_BASE_MS = 1;
@@ -221,7 +239,7 @@ export class SQLiteStore extends TaskStore {
         const memory = isMemory(this.path);
         if (!memory)
             mkdirSync(dirname(this.path), { recursive: true });
-        const db = new Database(this.path);
+        const db = new (loadSqlite())(this.path);
         // Only the synchronous part of the open path gets a real busy_timeout: the WAL
         // switch and the migrations cannot await a retry. See the class comment.
         db.pragma(`busy_timeout = ${this.busyBudgetMs}`);

package/dist/worker.d.ts

@@ -1,5 +1,6 @@
 import type { BackpressureOptions } from "./backpressure.js";
 import { TaskContext } from "./context.js";
+import type { PgExecutor } from "./store/pg-executor.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
 export { retryDelayMs, DEFAULT_RETRY_BACKOFF_MS, DEFAULT_RETRY_BACKOFF_MAX_MS } from "./backoff.js";
@@ -130,11 +131,13 @@ export declare class Worker {
         queues?: string[];
         busyTimeoutMs?: number;
     }): Worker;
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn: string, opts?: WorkerOptions & {
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs, which cairnq then shares instead of opening a second pool. */
+    static postgres(source: string | PgExecutor, opts?: WorkerOptions & {
         queues?: string[];
         max?: number;
+        schema?: string;
     }): Worker;
     get id(): string;
     task(handler: Handler): this;

package/dist/worker.js

@@ -133,11 +133,12 @@ export class Worker {
         worker.ownsStore = true;
         return worker;
     }
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn, opts = {}) {
-        const { queues = ["default"], max, ...rest } = opts;
-        const worker = new Worker(new PostgresStore(dsn, { max }), queues, rest);
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs, which cairnq then shares instead of opening a second pool. */
+    static postgres(source, opts = {}) {
+        const { queues = ["default"], max, schema, ...rest } = opts;
+        const worker = new Worker(new PostgresStore(source, { max, schema }), queues, rest);
         worker.ownsStore = true;
         return worker;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",
@@ -39,19 +39,21 @@
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
-  "dependencies": {
-    "better-sqlite3": "^13.0.2"
-  },
   "peerDependencies": {
+    "better-sqlite3": "^13.0.2",
     "pg": "^8.13.0"
   },
   "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     }
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
+    "better-sqlite3": "^13.0.2",
     "@types/node": "^22.7.0",
     "@types/pg": "^8.11.10",
     "pg": "^8.13.0",

package/src/client.ts

@@ -4,7 +4,15 @@ import { TaskCanceled, TaskFailed } from "./errors.js";
 import { isFailed, isSucceeded, type Task, type TaskRef, type TaskStatus } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
-import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
+import type { PgExecutor } from "./store/pg-executor.js";
+import type {
+  ListInput,
+  PurgeInput,
+  SubmitInput,
+  TaskStore,
+  WatchOptions,
+  WatchSignal,
+} from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
 import { DEFAULT_WAIT_TIMEOUT_MS, type PollOptions, pollWait, pollWaitByKey } from "./wait.js";
 
@@ -53,11 +61,16 @@ export class CairnQ {
     return new CairnQ(new SQLiteStore(path, { busyTimeoutMs }), client);
   }
 
-  /** Multi-host backend. `dsn` is a libpq connection string; requires the
-   * optional `pg` package. */
-  static postgres(dsn: string, opts: { max?: number } & ClientOptions = {}): CairnQ {
-    const { max, ...client } = opts;
-    return new CairnQ(new PostgresStore(dsn, { max }), client);
+  /** Multi-host backend. `source` is a libpq connection string — which requires
+   * the optional `pg` package — or a PgExecutor over a driver the application
+   * already runs (an ORM's pool, say), which cairnq then shares instead of
+   * opening a second one. */
+  static postgres(
+    source: string | PgExecutor,
+    opts: { max?: number; schema?: string } & ClientOptions = {},
+  ): CairnQ {
+    const { max, schema, ...client } = opts;
+    return new CairnQ(new PostgresStore(source, { max, schema }), client);
   }
 
   get store(): TaskStore {
@@ -146,6 +159,20 @@ export class CairnQ {
     return this._store.stats();
   }
 
+  /**
+   * Call `onSignal` when the tasks on `queues` may have changed. Returns an
+   * unsubscribe.
+   *
+   * Notify-accelerated polling, not an event log: a signal means "re-read now",
+   * and `stats()` / `list()` / `get()` are where the truth is. On Postgres an
+   * idle watch costs nothing and signals land in milliseconds; everywhere else
+   * the timer alone still delivers, so the same consumer code is correct either
+   * way. See TaskStore.watch for the full contract.
+   */
+  watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void {
+    return this._store.watch(opts, onSignal);
+  }
+
   /** Wait for a task to finish. Resolves with the terminal Task (any status);
    * throws TaskTimeout without stopping the task, so `wait(err.taskId)` picks the
    * same wait back up — from another process, or after a longer deadline. */

package/src/context.ts

@@ -3,6 +3,7 @@ import { asEnvelope, type FailReason, LostLease } from "./errors.js";
 import { cancelRequested, type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
+import type { PgSession } from "./store/pg-executor.js";
 import { type TaskDef, taskName } from "./task.js";
 import { pollWait } from "./wait.js";
 
@@ -201,6 +202,42 @@ export class TaskContext {
     return task;
   }
 
+  /**
+   * Finalize this task as succeeded, committing the caller's own writes in the
+   * SAME transaction as the settlement. Whatever `write` returns becomes the
+   * task's result.
+   *
+   *     await ctx.succeedIn(async (session) => {
+   *       await db.withSession(session).insert(pages).values(rendered)
+   *       return { pages: rendered.length }
+   *     })
+   *
+   * The alternative — write the rows, then settle — has a window between the two
+   * commits where the work is durable but the task still reads as running. A
+   * crash there re-runs the whole task, which for a render or an ingest means
+   * recomputing it, and for non-idempotent work means doing it twice.
+   *
+   * `session` is the driver's, so this needs a Postgres store built on a
+   * PgExecutor the application shares with its own driver; anything else throws.
+   * If the settlement finds the lease gone, `write`'s work is rolled back with
+   * it and LostLease is raised. Returns null if this task was already settled.
+   *
+   * `write` may be replayed if the backend retries the transaction — derive
+   * nothing inside it that cannot be derived twice.
+   */
+  async succeedIn<T>(write: (session: PgSession) => Promise<T>): Promise<Task | null> {
+    if (this.isSettled) return null;
+    const task = await this.owned(async () => {
+      const { task } = await this.store.completeIn<PgSession, T>(
+        { taskId: this.task.id, workerId: this.workerId },
+        write,
+      );
+      return task;
+    });
+    this.markSettled();
+    return task;
+  }
+
   /**
    * Finalize this task as failed, now. `error` may be a string reason, an Error,
    * a TaskError (which carries its own retryability), or a ready envelope.

package/src/index.ts

@@ -12,8 +12,19 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { ListenUnavailable } from "./store/pg-executor.js";
+export type { PgExecutor, PgSession, Row } from "./store/pg-executor.js";
+export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
-export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
+export type {
+  ListInput,
+  PurgeInput,
+  SubmitInput,
+  Conflict,
+  WatchOptions,
+  WatchSignal,
+} from "./store/base.js";
+export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
 export {
   STATUSES,

package/src/store/base.ts

@@ -201,6 +201,35 @@ export function statementParams(sql: string): readonly string[] {
  * them in one place is what stops SQLite and Postgres from drifting apart in
  * behavior; the shared SQL already stops them from drifting in wording.
  */
+/**
+ * Why `watch` is calling back.
+ *
+ * `queued` / `done` come from the store's push channel and name what moved;
+ * `poll` is the timer saying the watch cannot rule out a change. None of them
+ * carries state — the row is the truth.
+ */
+export interface WatchSignal {
+  reason: "queued" | "done" | "poll";
+  /** The queue a task was queued on. Only on `queued`. */
+  queue?: string;
+  /** The task that reached a terminal status. Only on `done`. */
+  taskId?: string;
+}
+
+export interface WatchOptions {
+  /** Restrict `queued` signals to these queues. Unset watches every queue. */
+  queues?: string[];
+  /**
+   * How often to signal in the absence of a push channel — and, where there is
+   * one, how long a dropped listener can go unnoticed. The default trades a
+   * dashboard's idle query rate against how stale it may look.
+   */
+  pollMs?: number;
+}
+
+/** See WatchOptions.pollMs. */
+export const DEFAULT_WATCH_POLL_MS = 2_000;
+
 export abstract class TaskStore {
   /** Set by useBackpressure; null means submit is ungated. */
   private gate: QueueDepthGate | null = null;
@@ -222,6 +251,37 @@ export abstract class TaskStore {
    */
   protected abstract tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
 
+  /**
+   * `tx`, but also handing `fn` the driver's own session so the CALLER can run
+   * their statements in the same transaction as the protocol's.
+   *
+   * This is what lets a task's settlement and the rows that task produced commit
+   * together. Without it the two are separate transactions and there is a window
+   * where the work is durable but the task still reads as unfinished — a crash
+   * there costs a full recomputation on retry, and for non-idempotent work costs
+   * more than that.
+   *
+   * Optional, because the session type is the driver's, not the protocol's: a
+   * store that has no session worth handing out simply does not implement it and
+   * `completeIn` reports that. Postgres implements it; SQLite does not.
+   */
+  protected txWithSession?<T>(fn: (fetch: Fetch, session: unknown) => Promise<T>): Promise<T>;
+
+  /**
+   * Register for this store's push channel, if it has one; returns an
+   * unsubscribe. A store without a push channel does not implement this, and
+   * `watch` degrades to its timer alone.
+   */
+  protected subscribePush?(onSignal: (signal: WatchSignal) => void): () => void;
+
+  /**
+   * Nudge the push channel back up if it has dropped. Called from `watch`'s
+   * timer, which is the only thing keeping a client-side subscriber alive: a
+   * process that never claims never calls claimWake, so without this a listener
+   * that died once would never come back there.
+   */
+  protected warmPush?(): void;
+
   /**
    * Whether it is worth opening the claim transaction at all. SQLite gates its
    * single write lock behind a read-only probe; Postgres readers don't block
@@ -460,6 +520,57 @@ export abstract class TaskStore {
     return out;
   }
 
+  /**
+   * Call `onSignal` when the tasks on `queues` may have changed — something was
+   * queued, or something finished.
+   *
+   * This is notify-ACCELERATED POLLING, not an event log, and the difference is
+   * the whole contract. Where a push channel is available (Postgres LISTEN) an
+   * idle watch costs nothing and a signal arrives within milliseconds of the
+   * event. Where it is not — a transaction-mode pooler refuses LISTEN, SQLite has
+   * no channel at all — the timer alone still delivers `poll` signals, so a
+   * consumer that re-reads on every signal is correct in both cases and merely
+   * less prompt in one.
+   *
+   * What it will NOT do is promise that a signal means something happened, or
+   * that every event produces its own signal. Treat a signal as "re-read now"
+   * and take the truth from `stats()` / `list()` / `get()`, which is where it
+   * lives. `reason` is a hint for reading less: a `done` signal names the task,
+   * so a dashboard can refresh that row instead of the list.
+   *
+   * Returns an unsubscribe. The timer is unref'd — watching does not hold a
+   * process open.
+   */
+  watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void {
+    const pollMs = Math.max(1, opts.pollMs ?? DEFAULT_WATCH_POLL_MS);
+    const queues = opts.queues ?? null;
+    let live = true;
+    const emit = (signal: WatchSignal): void => {
+      // A signal delivered after unsubscribe would have the consumer re-reading
+      // a store it has stopped caring about, possibly a closed one.
+      if (live) onSignal(signal);
+    };
+    const unsubscribe = this.subscribePush?.((signal) => {
+      // A queued signal names its queue, so a watch scoped to some queues can
+      // drop the rest. A done signal names only the task — which queue it was on
+      // is not in the notification, so it is never filtered out.
+      if (signal.reason === "queued" && queues && signal.queue && !queues.includes(signal.queue)) {
+        return;
+      }
+      emit(signal);
+    });
+    const timer = setInterval(() => {
+      this.warmPush?.();
+      emit({ reason: "poll" });
+    }, pollMs);
+    timer.unref?.();
+    return () => {
+      live = false;
+      unsubscribe?.();
+      clearInterval(timer);
+    };
+  }
+
   /**
    * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
    *
@@ -636,6 +747,45 @@ export abstract class TaskStore {
     });
   }
 
+  /**
+   * `complete`, with the caller's own writes committed in the same transaction.
+   *
+   * `fn` runs first and whatever it returns becomes the task's result; the
+   * settlement is the last statement in the transaction. So a lost lease — the
+   * settlement matching no row — rolls the caller's writes back with it, and
+   * there is no ordering in which the work is recorded but the task is not.
+   *
+   * The settlement runs LAST rather than checking ownership up front on purpose:
+   * the ownership predicate lives in the protocol's complete.sql, and a
+   * fail-fast pre-check here would be a second copy of it, free to drift. The
+   * cost of that choice is that a doomed attempt does its work before finding
+   * out, which is the rare path.
+   *
+   * `fn` must be replayable for the same reason `tx`'s callback must be.
+   */
+  async completeIn<S, T>(
+    input: { taskId: string; workerId: string },
+    fn: (session: S) => Promise<T>,
+  ): Promise<{ task: Task; value: T }> {
+    if (!this.txWithSession) {
+      throw new Error(
+        "this store cannot share a transaction with the caller — " +
+          "completeIn requires a Postgres store (see PgExecutor)",
+      );
+    }
+    return this.txWithSession(async (fetch, session) => {
+      const value = await fn(session as S);
+      const rows = await fetch("complete", {
+        id: input.taskId,
+        worker_id: input.workerId,
+        result: value == null ? null : dumpJson(value),
+      });
+      // Rolls back `fn`'s writes along with the settlement that did not land.
+      if (!rows.length) throw new LostLease(input.taskId);
+      return { task: rowToTask(rows[0]), value };
+    });
+  }
+
   async fail(input: {
     taskId: string;
     workerId: string;

package/src/store/pg-executor.ts

@@ -0,0 +1,90 @@
+/**
+ * The seam between PostgresStore and whatever actually talks to Postgres.
+ *
+ * PostgresStore owns the *dialect* — the protocol's named-parameter SQL rewritten
+ * to `$n`, the migration ledger, the LISTEN policy. It does not own the
+ * *connection*. Applications that already run a Postgres driver (an ORM, a pool
+ * they size themselves) pass their own executor and cairnq joins that session
+ * instead of opening a second one, which is what makes a task's settlement
+ * commit in the same transaction as the rows the task produced.
+ *
+ * Implementing one is small — see `createPoolExecutor` below for the reference
+ * implementation over `pg`, and PROTOCOL.md for the two things an adapter must
+ * get right that are easy to miss: int8 must come back as a JS number (every
+ * cairnq bigint is an epoch-ms or a counter, all inside the safe range), and
+ * jsonb must come back as an object, not a string.
+ */
+
+/** A row as the driver hands it back: column name -> value. */
+export type Row = Record<string, unknown>;
+
+/**
+ * Somewhere statements can run. The same shape whether it is a pool (each call
+ * on some connection) or one transaction's dedicated connection — the store's
+ * statements do not care, and this is what lets `tx` hand the same interface to
+ * its callback.
+ */
+export interface PgSession {
+  /**
+   * One parameterised statement, `$1`-style. `values` is positional and may
+   * legitimately contain nulls — a null parameter is "this filter is off" in
+   * several protocol statements, not a missing argument.
+   */
+  query(text: string, values: readonly unknown[]): Promise<Row[]>;
+  /**
+   * Parameterless SQL that may hold several statements, for migration DDL.
+   * Separate from `query` because it must go over the simple query protocol:
+   * the extended protocol a parameterised call uses accepts only one statement,
+   * and every migration is a script.
+   */
+  exec(sql: string): Promise<void>;
+}
+
+/** A session that can also open transactions, listen, and be shut down. */
+export interface PgExecutor extends PgSession {
+  /**
+   * Run `fn` inside one transaction on one dedicated connection, committing if
+   * it returns and rolling back if it throws. The store relies on both halves:
+   * a claim that cannot see its own `recover_leases` is a double-dispatch, and a
+   * keyed submit that commits half way poisons the key.
+   */
+  tx<T>(fn: (session: PgSession) => Promise<T>): Promise<T>;
+
+  /**
+   * Subscribe a dedicated connection to `channels`. Optional: an executor that
+   * omits it (or a Postgres that refuses LISTEN) costs latency, never
+   * correctness — the store falls back to plain polling, which is the contract
+   * PROTOCOL.md gives for push wakeups.
+   *
+   * Resolves with a function that stops listening. `onClose` reports a
+   * connection that dropped on its own, so the store can degrade and retry.
+   *
+   * Throw `ListenUnavailable` when this Postgres will never accept LISTEN — a
+   * transaction-mode pooler, say. Any other rejection is read as transient and
+   * retried with backoff, so a permanent condition raised as a plain Error
+   * becomes a reconnect loop that cannot succeed.
+   */
+  listen?(
+    channels: readonly string[],
+    onNotify: (channel: string, payload: string | undefined) => void,
+    onClose: () => void,
+  ): Promise<() => void>;
+
+  /**
+   * Release this executor's resources. Called by PostgresStore.close() ONLY for
+   * an executor the store created itself: an injected one belongs to the caller,
+   * whose other work would not survive cairnq closing it.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * LISTEN will not work on this connection, and retrying cannot change that.
+ * See `PgExecutor.listen`.
+ */
+export class ListenUnavailable extends Error {
+  constructor(message = "LISTEN is not available on this connection") {
+    super(message);
+    this.name = "ListenUnavailable";
+  }
+}

package/src/store/pg-pool.ts

@@ -0,0 +1,156 @@
+import type * as PG from "pg";
+
+import { ListenUnavailable, type PgExecutor, type PgSession, type Row } from "./pg-executor.js";
+
+// `pg` is an optional dependency: the SDK is SQLite-first, so it's loaded lazily
+// the first time a pool-backed executor is built. Absent -> a clear install hint.
+// An application that brings its own executor never reaches this.
+let pgModule: typeof import("pg") | null = null;
+async function loadPg(): Promise<typeof import("pg")> {
+  if (pgModule) return pgModule;
+  let mod: { default?: typeof import("pg") } & typeof import("pg");
+  try {
+    mod = (await import("pg")) as never;
+  } catch {
+    throw new Error("PostgresStore requires the 'pg' package — install it (e.g. `npm i pg`)");
+  }
+  const pg = (mod.default ?? mod) as typeof import("pg");
+  // Postgres returns bigint (int8, OID 20) as a string to avoid precision loss.
+  // Every cairnq bigint is an epoch-ms or a counter, all within Number's safe
+  // integer range, so parse to number once (globally) to match the Task model
+  // (*_ms typed as number, same as the SQLite SDK). Set before any query runs.
+  pg.types.setTypeParser(pg.types.builtins.INT8, (v: string) => (v == null ? null : Number(v)));
+  pgModule = pg;
+  return pg;
+}
+
+/**
+ * Roll back on the way out of a failed transaction, without letting the rollback
+ * become the error the caller sees. A dropped connection fails both the statement
+ * and the rollback, and it is the first one that says what went wrong.
+ */
+async function rollbackQuietly(client: PG.PoolClient): Promise<void> {
+  try {
+    await client.query("rollback");
+  } catch {
+    // Already rolled back, or the connection is gone. Either way the original
+    // error is the one worth propagating.
+  }
+}
+
+/** The PgSession face of one pg client or pool. */
+function session(q: Pick<PG.PoolClient, "query">): PgSession {
+  return {
+    async query(text: string, values: readonly unknown[]): Promise<Row[]> {
+      return (await q.query(text, values as unknown[])).rows;
+    },
+    async exec(sql: string): Promise<void> {
+      // No values: pg sends this over the simple query protocol, which is what
+      // makes a multi-statement migration script legal here and not in query().
+      await q.query(sql);
+    },
+  };
+}
+
+/**
+ * A Postgres identifier that is safe to interpolate — cairnq quotes the schema
+ * name, and a name that could close that quote could rewrite the statement.
+ * Deliberately narrower than what Postgres accepts: a schema cairnq is asked to
+ * live in is a deployment decision, not a place to be clever.
+ */
+const PLAIN_IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * The built-in executor: a `pg.Pool` over a libpq DSN. What `CairnQ.postgres(dsn)`
+ * uses, and the reference for what an adapter over another driver must do.
+ *
+ * Creating it does not connect — `pg.Pool` is lazy, and the store's first
+ * statement (the migration ledger) is what proves the database is reachable.
+ *
+ * `schema` puts cairnq's tables in a schema of their own rather than in whatever
+ * the connection's search_path leads with. The protocol's SQL names no schema, so
+ * this is a per-connection `search_path` and not one statement changes.
+ */
+export async function createPoolExecutor(
+  dsn: string,
+  opts: { max?: number; schema?: string } = {},
+): Promise<PgExecutor> {
+  const pg = await loadPg();
+  const schema = opts.schema;
+  if (schema !== undefined && !PLAIN_IDENT.test(schema)) {
+    throw new Error(
+      `schema must be a plain identifier (letters, digits, _ and $, not starting ` +
+        `with a digit), got ${JSON.stringify(schema)}`,
+    );
+  }
+  const pool = new pg.Pool({ connectionString: dsn, max: opts.max });
+  if (schema) {
+    // Queued on the connection before it is handed out, so every statement this
+    // pool ever runs — migrations included — resolves in the right schema. Pooled
+    // connections come and go, which is why this is per-connection rather than a
+    // one-off at startup.
+    pool.on("connect", (client) => {
+      void client.query(`set search_path to "${schema}"`);
+    });
+  }
+  if (schema) {
+    // Created once, here, rather than from the connect handler (which would ask
+    // for CREATE privilege on every new connection) or from the migrations
+    // (which name no schema, by design). Without it the first `create table`
+    // fails with "no schema has been selected to create in", which says nothing
+    // about the cause. This is the one thing that makes building the executor
+    // connect; without `schema` it stays lazy.
+    try {
+      await pool.query(`create schema if not exists "${schema}"`);
+    } catch (e) {
+      await pool.end();
+      throw e;
+    }
+  }
+  const poolSession = session(pool);
+
+  return {
+    query: poolSession.query,
+    exec: poolSession.exec,
+
+    async tx<T>(fn: (s: PgSession) => Promise<T>): Promise<T> {
+      const client = await pool.connect();
+      try {
+        await client.query("begin");
+        const out = await fn(session(client));
+        await client.query("commit");
+        return out;
+      } catch (e) {
+        await rollbackQuietly(client);
+        throw e;
+      } finally {
+        client.release();
+      }
+    },
+
+    async listen(channels, onNotify, onClose): Promise<() => void> {
+      // Built from the raw DSN rather than taken from the pool: a listener holds
+      // its connection for its whole life, and a pooled one would be a slot the
+      // store never gives back. If `opts` ever grows connection-level settings
+      // (ssl, application_name), the listener must receive them too.
+      const client = new pg.Client({ connectionString: dsn });
+      await client.connect(); // failure here is transient: caller retries with backoff
+      client.on("notification", (msg) => onNotify(msg.channel, msg.payload));
+      // A dropped listener degrades to polling; the store reconnects on the next wake.
+      client.on("error", () => onClose());
+      try {
+        await client.query(channels.map((c) => `listen ${c}`).join("; "));
+      } catch (e) {
+        void client.end().catch(() => {});
+        // Connected, but LISTEN was refused (e.g. a transaction-mode pooler) —
+        // deterministic, so tell the store not to retry.
+        throw new ListenUnavailable(e instanceof Error ? e.message : undefined);
+      }
+      return () => void client.end().catch(() => {});
+    },
+
+    async close(): Promise<void> {
+      await pool.end();
+    },
+  };
+}