@zmdb/orm 1.0.0-beta.1

package/src/outbox/sql.ts

@@ -0,0 +1,179 @@
+import {
+  createQueryCompiler,
+  dialectTraits,
+  quoteIdentifier,
+  type CompiledQuery,
+  type DialectOutbox,
+  type DialectTarget,
+} from '@zmdb/sql';
+
+export const OUTBOX_TABLE = 'zmdb_outbox';
+export type OutboxStatus = 'pending' | 'delivered' | 'dead';
+
+const PENDING: OutboxStatus = 'pending';
+
+export interface OutboxMigration {
+  readonly version: number;
+  readonly name: string;
+  readonly up: string;
+  readonly down: string;
+}
+
+/**
+ * Most dialects index only pending rows. Dialects that cannot represent the
+ * predicate use the full composite index with `status` first to preserve a
+ * useful pending-row prefix instead of degrading to an unindexed scan.
+ */
+export function outboxPendingIndexDdl(dialect: DialectTarget): string {
+  const definition = {
+    name: 'zmdb_outbox_pending',
+    table: OUTBOX_TABLE,
+    columns: ['status', 'lease_until', 'created_at'],
+    ...(outboxDialect(dialect).pendingIndex === 'full' ? {} : { where: "status = 'pending'" }),
+  };
+  const statements = dialect.migrations.emitSchemaObject({
+    kind: 'create_index',
+    definition,
+  });
+  if (statements.length !== 1 || statements[0] === undefined) {
+    throw new TypeError(`${dialect.name} outbox index emission must return exactly one statement`);
+  }
+  return statements[0];
+}
+
+function outboxDialect(dialect: DialectTarget): DialectOutbox {
+  if (dialect.outbox === undefined) {
+    throw new TypeError(`${dialect.name} does not provide an outbox DDL strategy`);
+  }
+  return dialect.outbox;
+}
+
+/** The declared outbox table's migration DDL, including the defaults its type tags cannot carry. */
+export function outboxTableDdl(dialect: DialectTarget): string {
+  const q = (name: string) => quoteIdentifier(dialect, name);
+  const traits = dialectTraits(dialect);
+  const outbox = outboxDialect(dialect);
+  const timestamp = traits.types.timestamp;
+  // MySQL refuses TEXT primary keys and TEXT columns in an index without a prefix
+  // length. These three values are bounded by construction, so the migration uses
+  // bounded storage there while the application type remains string.
+  const text = traits.types.text;
+  const idType = outbox.boundedTextType(36);
+  const statusType = outbox.boundedTextType(16);
+  const leaseOwnerType = outbox.boundedTextType(36);
+  return (
+    `${outbox.createTable} ${q(OUTBOX_TABLE)} (` +
+    `${q('id')} ${idType} PRIMARY KEY, ` +
+    `${q('topic')} ${text} NOT NULL, ` +
+    `${q('payload')} ${text} NOT NULL, ` +
+    `${q('status')} ${statusType} NOT NULL DEFAULT 'pending', ` +
+    `${q('attempts')} ${traits.types.integer} NOT NULL DEFAULT 0, ` +
+    `${q('created_at')} ${timestamp} NOT NULL DEFAULT ${outbox.createdAtDefault}, ` +
+    `${q('lease_owner')} ${leaseOwnerType} NOT NULL DEFAULT '', ` +
+    `${q('lease_until')} ${timestamp} NOT NULL DEFAULT ${outbox.epochLiteral}, ` +
+    `${q('delivered_at')} ${timestamp}, ` +
+    `${q('last_error')} ${text})`
+  );
+}
+
+/** A normal migration value applications can place in their ordered migration list. */
+export function outboxMigration(version: number, dialect: DialectTarget): OutboxMigration {
+  return {
+    version,
+    name: 'create_zmdb_outbox',
+    up: `${outboxTableDdl(dialect)}; ${outboxPendingIndexDdl(dialect)}`,
+    down: `DROP TABLE ${quoteIdentifier(dialect, OUTBOX_TABLE)}`,
+  };
+}
+
+export function outboxCandidatesQuery(
+  dialect: DialectTarget,
+  args: { readonly now: Date; readonly batch: number },
+): CompiledQuery {
+  return createQueryCompiler(dialect)
+    .selectFrom(OUTBOX_TABLE)
+    .select(['id'])
+    .where('status', '=', PENDING)
+    .where('lease_until', '<', args.now)
+    .orderBy('created_at', 'asc')
+    .limit(args.batch)
+    .compile();
+}
+
+export function outboxClaimQuery(
+  dialect: DialectTarget,
+  args: {
+    readonly now: Date;
+    readonly token: string;
+    readonly leaseUntil: Date;
+    readonly ids: readonly string[];
+  },
+): CompiledQuery {
+  return createQueryCompiler(dialect)
+    .updateTable(OUTBOX_TABLE)
+    .set({ lease_owner: args.token, lease_until: args.leaseUntil })
+    .where('status', '=', PENDING)
+    .where('lease_until', '<', args.now)
+    .whereIn('id', args.ids)
+    .compile();
+}
+
+export function outboxReadBackQuery(dialect: DialectTarget, args: { readonly token: string }): CompiledQuery {
+  return createQueryCompiler(dialect)
+    .selectFrom(OUTBOX_TABLE)
+    .select(['id', 'topic', 'payload', 'attempts'])
+    .where('lease_owner', '=', args.token)
+    .compile();
+}
+
+export function outboxMarkDeliveredQuery(
+  dialect: DialectTarget,
+  args: {
+    readonly id: string;
+    readonly token: string;
+    readonly deliveredAt: Date;
+    readonly attempts: number;
+  },
+): CompiledQuery {
+  return createQueryCompiler(dialect)
+    .updateTable(OUTBOX_TABLE)
+    .set({ status: 'delivered', delivered_at: args.deliveredAt, attempts: args.attempts })
+    .where('id', '=', args.id)
+    .where('lease_owner', '=', args.token)
+    .compile();
+}
+
+export function outboxMarkRetryQuery(
+  dialect: DialectTarget,
+  args: {
+    readonly id: string;
+    readonly token: string;
+    readonly attempts: number;
+    readonly lastError: string;
+    readonly leaseUntil: Date;
+  },
+): CompiledQuery {
+  return createQueryCompiler(dialect)
+    .updateTable(OUTBOX_TABLE)
+    .set({ attempts: args.attempts, last_error: args.lastError, lease_until: args.leaseUntil })
+    .where('id', '=', args.id)
+    .where('lease_owner', '=', args.token)
+    .compile();
+}
+
+export function outboxMarkDeadQuery(
+  dialect: DialectTarget,
+  args: {
+    readonly id: string;
+    readonly token: string;
+    readonly attempts: number;
+    readonly lastError: string;
+  },
+): CompiledQuery {
+  return createQueryCompiler(dialect)
+    .updateTable(OUTBOX_TABLE)
+    .set({ status: 'dead', attempts: args.attempts, last_error: args.lastError })
+    .where('id', '=', args.id)
+    .where('lease_owner', '=', args.token)
+    .compile();
+}

package/src/relations/index.ts

@@ -0,0 +1,221 @@
+import type { SchemaIR } from '@zmdb/schema/ir';
+import { resolveRelation } from '@zmdb/schema/relations';
+import {
+  dialectName,
+  dialectTraits,
+  formatPlaceholder,
+  quoteIdentifier,
+  renderPredicate,
+  UnsupportedFeatureError,
+  type ComparisonPredicate,
+  type DialectTarget,
+} from '@zmdb/sql';
+
+export type PopulateDialect = DialectTarget;
+
+export interface PopulateQuery {
+  readonly kind: 'join' | 'batched';
+  readonly sql: string;
+  readonly parameters: readonly unknown[];
+}
+
+function sanitizeKeys<T>(keys: readonly T[]): T[] {
+  const result: T[] = [];
+  const seen = new Set<T>();
+  for (const k of keys) {
+    if (k !== null && k !== undefined && !seen.has(k)) {
+      seen.add(k);
+      result.push(k);
+    }
+  }
+  return result;
+}
+
+function sameKeyValue(left: unknown, right: unknown): boolean {
+  if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  return Object.is(left, right);
+}
+
+function sanitizeCompositeKeys(
+  ir: SchemaIR,
+  relationName: string,
+  keys: readonly unknown[],
+  arity: number,
+): readonly (readonly unknown[])[] {
+  const result: unknown[][] = [];
+  for (const key of keys) {
+    if (key === null || key === undefined) continue;
+    if (!Array.isArray(key)) {
+      throw new Error(
+        `${ir.table}.${relationName}: composite-key populate expects a ${String(arity)}-column tuple for every parent`,
+      );
+    }
+    if (key.length !== arity) {
+      throw new Error(
+        `${ir.table}.${relationName}: composite-key populate expected ${String(arity)} values, received ${String(key.length)}`,
+      );
+    }
+    if (key.some(value => value === null || value === undefined)) continue;
+    if (result.some(existing => existing.every((value, index) => sameKeyValue(value, key[index])))) continue;
+    result.push([...key]);
+  }
+  return result;
+}
+
+/**
+ * Compile a populate hint into SQL: a to-one becomes an `INNER JOIN`, a to-many a batched
+ * `IN (…)` select over the parent keys.
+ *
+ * Takes the declaring table's IR and a relation name rather than a relation object, which is
+ * what makes the two spellings one: the columns on either side of the `ON` come out of
+ * `resolveRelation`, the same call `@zmdb/orm`'s `populate` makes.
+ */
+export function compilePopulate(
+  ir: SchemaIR,
+  relationName: string,
+  dialect: PopulateDialect,
+  parentIds: readonly unknown[] = [],
+  targetFilters: readonly ComparisonPredicate[] = [],
+  schemas: readonly SchemaIR[] = [],
+): PopulateQuery {
+  const rel = resolveRelation(ir, relationName);
+  const q = (name: string): string => quoteIdentifier(dialect, name);
+  const targetIr = schemas.find(schema => schema.table === rel.targetTable);
+  const sourceTable = ir.physicalTable;
+  const targetTable = targetIr?.physicalTable ?? rel.targetTable;
+  const physicalColumn = (schema: SchemaIR | undefined, declared: string): string => {
+    if (schema === undefined) return declared;
+    const separator = declared.lastIndexOf('.');
+    const property = separator === -1 ? declared : declared.slice(separator + 1);
+    const physical = schema.columns.find(column => column.name === property)?.physicalName;
+    if (physical === undefined) return declared;
+    if (separator === -1) return physical;
+    const qualifier = declared.slice(0, separator);
+    return `${qualifier === schema.table ? schema.physicalTable : qualifier}.${physical}`;
+  };
+  const parentKeys = rel.parentKey.map(column => physicalColumn(ir, column));
+  const targetKeys = rel.targetKey.map(column => physicalColumn(targetIr, column));
+  const physicalFilters = targetFilters.map(predicate => ({
+    ...predicate,
+    col: physicalColumn(targetIr, predicate.col),
+  }));
+  const renderFilters = (parameters: unknown[]): string => {
+    if (physicalFilters.length === 0) return '';
+    const body = physicalFilters
+      .map((predicate, index) => {
+        const rendered = renderPredicate(dialect, predicate, parameters);
+        return index === 0 ? rendered : `${predicate.connector ?? 'AND'} ${rendered}`;
+      })
+      .join(' ');
+    const grouped = targetFilters.some((predicate, index) => index > 0 && predicate.connector === 'OR');
+    return `AND ${grouped ? `(${body})` : body}`;
+  };
+  if (!rel.toMany) {
+    const parameters: unknown[] = [];
+    const filtered = physicalFilters.length > 0;
+    const onFilters = renderFilters(parameters);
+    const conditions = parentKeys.map((parentKey, index) => {
+      const targetKey = targetKeys[index];
+      if (targetKey === undefined) {
+        throw new Error(`${ir.table}.${relationName}: resolved relation keys have different lengths`);
+      }
+      return `${q(sourceTable)}.${q(parentKey)} = ${q(targetTable)}.${q(targetKey)}`;
+    });
+    const sql =
+      `SELECT * FROM ${q(sourceTable)} ${filtered ? 'LEFT' : 'INNER'} JOIN ${q(targetTable)} ` +
+      `ON ${conditions.join(' AND ')}` +
+      (onFilters.length === 0 ? '' : ` ${onFilters}`);
+    return { kind: 'join', sql, parameters };
+  }
+  if (parentIds.length === 0) {
+    return { kind: 'batched', sql: `SELECT * FROM ${q(targetTable)} WHERE 1 = 0`, parameters: [] };
+  }
+  if (targetKeys.length === 1) {
+    const sanitized = sanitizeKeys(parentIds);
+    if (sanitized.length === 0) {
+      return { kind: 'batched', sql: `SELECT * FROM ${q(targetTable)} WHERE 1 = 0`, parameters: [] };
+    }
+    const [targetKey] = targetKeys;
+    if (targetKey === undefined) {
+      throw new Error(`${ir.table}.${relationName}: resolved relation has no target key`);
+    }
+    const inList = sanitized.map((_, i) => formatPlaceholder(dialect, i + 1)).join(', ');
+    const parameters: unknown[] = [...sanitized];
+    const filters = renderFilters(parameters);
+    const sql =
+      `SELECT * FROM ${q(targetTable)} WHERE ${q(targetKey)} IN (${inList})` +
+      (filters.length === 0 ? '' : ` ${filters}`);
+    return { kind: 'batched', sql, parameters };
+  }
+  if (!dialectTraits(dialect).rowValueIn) {
+    const name = dialectName(dialect);
+    throw new UnsupportedFeatureError(
+      `composite-key populate for relation "${relationName}"`,
+      name,
+      `${ir.table}.${relationName}: dialect "${name}" does not support row-value IN for a composite-key populate`,
+    );
+  }
+  const sanitized = sanitizeCompositeKeys(ir, relationName, parentIds, targetKeys.length);
+  if (sanitized.length === 0) {
+    return { kind: 'batched', sql: `SELECT * FROM ${q(targetTable)} WHERE 1 = 0`, parameters: [] };
+  }
+  const parameters: unknown[] = [];
+  const inList = sanitized
+    .map(tuple => {
+      const placeholders = tuple.map(value => {
+        parameters.push(value);
+        return formatPlaceholder(dialect, parameters.length);
+      });
+      return `(${placeholders.join(', ')})`;
+    })
+    .join(', ');
+  const columns = targetKeys.map(targetKey => q(targetKey)).join(', ');
+  const filters = renderFilters(parameters);
+  const sql =
+    `SELECT * FROM ${q(targetTable)} WHERE (${columns}) IN (${inList})` + (filters.length === 0 ? '' : ` ${filters}`);
+  return { kind: 'batched', sql, parameters };
+}
+
+/**
+ * Attach a populated relation to a parent row, without mutating it.
+ *
+ * The type widening is `Populated<T, K>` in `../derive/query.ts`, which reads the declared
+ * relation property; this only puts the value there.
+ */
+export function attachPopulated<P extends Record<string, unknown>, N extends string, V>(
+  parent: P,
+  name: N,
+  value: V,
+): P & { [K in N]: V } {
+  // boundary: a computed key in an object literal widens to `string`, so TS types
+  // this spread as `P & { [x: string]: V }`. `name` is the literal `N` at the call
+  // site, which is what the return type states.
+  return { ...parent, [name]: value } as P & { [K in N]: V };
+}
+
+/**
+ * A row from a join written against two tables directly. LEFT: the joined columns may be
+ * absent, so they come back optional.
+ *
+ * `../derive/query.ts` has a `JoinRow<T, K, Kind>` that names the joined side by relation
+ * key instead; this is the form for a join whose target is not a declared relation of the
+ * base table.
+ */
+export type JoinRow<Base, Joined, Kind extends 'inner' | 'left' = 'left'> = Kind extends 'inner'
+  ? Base & Joined
+  : Base & Partial<Joined>;
+
+/** Rename aliased columns per a { alias: outKey } map (stable, non-mutating). */
+export function aliasRow<Row extends Record<string, unknown>>(
+  row: Row,
+  map: Readonly<Record<string, string>>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...row };
+  for (const [alias, outKey] of Object.entries(map)) {
+    if (alias in out) {
+      out[outKey] = out[alias];
+      delete out[alias]; // rename: drop the original aliased key
+    }
+  }
+  return out;
+}

package/src/replicas/index.ts

@@ -0,0 +1,51 @@
+import { type CompiledQuery } from '@zmdb/sql';
+
+// Read-replica routing — see ./SPEC.md.
+import { type Driver } from '../index.js';
+
+export interface ReplicaOptions {
+  primary: Driver;
+  replicas: readonly Driver[];
+  pick?: (replicas: readonly Driver[], nextIndex: number) => Driver;
+}
+
+export function isWrite(sql: string): boolean {
+  const s = sql.trimStart().toUpperCase();
+  return s.startsWith('INSERT') || s.startsWith('UPDATE') || s.startsWith('DELETE');
+}
+
+/** Wrap primary+replicas into a single Driver that routes reads to replicas. */
+export function withReplicas(opts: ReplicaOptions): Driver {
+  const { primary, replicas } = opts;
+  let rr = 0;
+  const pick = (query: CompiledQuery): Driver => {
+    if (isWrite(query.text) || replicas.length === 0) return primary;
+    const driver = opts.pick ? opts.pick(replicas, rr) : replicas[rr % replicas.length];
+    rr = (rr + 1) % replicas.length;
+    // `replicas` is non-empty here (checked above), so the modulo index always
+    // hits — but a custom `pick` is caller code, so fall back to the primary
+    // rather than crashing on a bad index.
+    return driver ?? primary;
+  };
+
+  const canStream =
+    typeof primary.stream === 'function' && replicas.every(driver => typeof driver.stream === 'function');
+  return {
+    dialect: primary.dialect,
+    execute(query, executeOpts) {
+      return pick(query).execute(query, executeOpts);
+    },
+    ...(canStream
+      ? {
+          stream(query: CompiledQuery, executeOpts?: Parameters<NonNullable<Driver['stream']>>[1]) {
+            const driver = pick(query);
+            const stream = driver.stream;
+            if (typeof stream !== 'function') {
+              throw new Error('replica routing selected a driver without stream support');
+            }
+            return stream.call(driver, query, executeOpts);
+          },
+        }
+      : {}),
+  };
+}

package/src/seeding/index.ts

@@ -0,0 +1,72 @@
+import { type CreateDTO, type DeclaredTable, type TaggedSchema } from '@zmdb/schema';
+import { objectTypeFromIR, type ObjectIR } from '@zmdb/schema/ir';
+// Deterministic seeding — see ./SPEC.md.
+//
+// This module used to live in `@zmdb/schema/seeding` and generate its values from a
+// walk of its own over `schema.columns`: a `switch` on `col.type` returning a random number
+// for an integer, a random `s…` for anything string-ish, and a member of `flags.enum` for an
+// enum. It was the fifth walker over column metadata, and it had the failure mode all five
+// shared — it read part of what a column says. `Min<18>`, `Max<120>`, `Pattern<…>`,
+// `MinLength`, a `json` payload shape and nullability were all invisible to it, so seeding a
+// table with any of them produced rows the table's own validator rejects.
+//
+// It generates from the IR now, through the same sampler `random<T>()` uses, which reads the
+// whole vocabulary and *refuses* what it cannot satisfy rather than guessing. Two
+// consequences worth stating, because both are visible to a caller:
+//
+//   - The rows honour the constraints. A `Min<18>` column is seeded within its bounds.
+//   - A `Pattern<…>` column is refused, with the column named. Nothing inverts a regular
+//     expression, so the alternative is a value that violates the pattern — which is what
+//     used to happen, silently, and surfaced later as a validation failure in a test whose
+//     subject was something else.
+//
+// Seeding lives in ORM because its sampler ships in `@zmdb/validator`, which
+// depends on `@zmdb/schema/ir`. The dependencies point inward from ORM. That is also the honest home: a seeded row exists to be handed to
+// `repository.create`, and now it type-checks as one.
+import { random } from '@zmdb/validator';
+
+/** Deterministic PRNG (mulberry32). Same seed ⇒ same sequence. */
+export function makeRng(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export interface SeedOptions {
+  seed?: number;
+  count: number;
+}
+
+/**
+ * The create shape with its optional properties dropped — the columns a caller *must* supply.
+ *
+ * The sampler fills every property of an object it is given, including the optional ones, and
+ * that is right for `random<T>()`: a sample of a type is a value of that type. It is wrong
+ * here. A column is optional in `CreateDTO` because the database has a default for it, and
+ * seeding a value over the default is how a seeded row stops resembling an inserted one.
+ */
+function requiredColumns(shape: ObjectIR): ObjectIR {
+  return { ...shape, properties: shape.properties.filter(property => !property.optional) };
+}
+
+/**
+ * `count` rows shaped like `T`'s create DTO, reproducible from `seed`.
+ *
+ * Typed as `CreateDTO<T>[]`, which the column-map version could not be: it built its rows
+ * from the lossy projection and had no way to tell the compiler what it had made. `random`'s
+ * type parameter is inferred from the return type here, so there is no assertion — and no
+ * type argument either, which is what keeps the transformer out of a call whose shape is only
+ * known at runtime.
+ */
+export function seedRows<T extends DeclaredTable>(schema: TaggedSchema<T>, opts: SeedOptions): CreateDTO<T>[] {
+  const rng = makeRng(opts.seed ?? 1);
+  const shape = requiredColumns(objectTypeFromIR(schema.ir, 'create'));
+  const rows: CreateDTO<T>[] = [];
+  for (let i = 0; i < opts.count; i++) rows.push(random(shape, rng));
+  return rows;
+}

package/src/streaming/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Add repository ergonomics around a driver's deliberately small stream
+ * surface. The driver owns its cursor; this wrapper owns single-shot use,
+ * per-row mapping, and exactly one cleanup path.
+ */
+export function createRepositoryStream<Raw, Row>(
+  open: () => AsyncIterable<Raw>,
+  map: (row: Raw) => Row,
+  signal?: AbortSignal,
+): AsyncIterable<Row> & AsyncDisposable {
+  let started = false;
+  let disposed = false;
+  let active: AsyncIterator<Raw> | undefined;
+  let closing: Promise<void> | undefined;
+
+  const close = (): Promise<void> => {
+    if (closing !== undefined) return closing;
+    disposed = true;
+    const iterator = active;
+    active = undefined;
+    closing = (async () => {
+      if (iterator?.return !== undefined) await iterator.return();
+    })();
+    return closing;
+  };
+
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<Row> {
+      if (started) throw new Error('repository stream is single-shot');
+      if (disposed) throw new Error('repository stream has been disposed');
+      started = true;
+
+      const iterate = async function* (): AsyncGenerator<Row, void, unknown> {
+        let completed = false;
+        try {
+          if (disposed) throw new Error('repository stream has been disposed');
+          signal?.throwIfAborted();
+          active = open()[Symbol.asyncIterator]();
+
+          for (;;) {
+            signal?.throwIfAborted();
+            const iterator = active;
+            if (iterator === undefined) return;
+            const next = await iterator.next();
+            if (disposed) return;
+            signal?.throwIfAborted();
+            if (next.done) {
+              completed = true;
+              active = undefined;
+              disposed = true;
+              return;
+            }
+            yield map(next.value);
+          }
+        } finally {
+          if (!completed) await close();
+        }
+      };
+
+      return iterate();
+    },
+
+    [Symbol.asyncDispose](): Promise<void> {
+      return close();
+    },
+  };
+}

package/src/testing/repository.fixture.ts

@@ -0,0 +1,44 @@
+import { type ColumnIR } from '@zmdb/schema/ir';
+import { type CompiledQuery } from '@zmdb/sql';
+
+import { type Driver } from '../index.js';
+import { postgresDialect } from './official-dialects.fixture.js';
+
+export function column(name: string, sql: ColumnIR['sql'], overrides: Partial<ColumnIR> = {}): ColumnIR {
+  return {
+    name,
+    physicalName: name,
+    sql,
+    nullable: false,
+    primaryKey: false,
+    serial: false,
+    unique: false,
+    hasDefault: false,
+    sensitive: false,
+    constraints: {},
+    rules: [],
+    ...overrides,
+  };
+}
+
+interface RecordingDriver extends Driver {
+  readonly calls: CompiledQuery[];
+}
+
+type DriverAnswer = (
+  query: CompiledQuery,
+  call: number,
+) => readonly Record<string, unknown>[] | Promise<readonly Record<string, unknown>[]>;
+
+export function recordingDriver(answer: DriverAnswer): RecordingDriver {
+  const calls: CompiledQuery[] = [];
+  return {
+    dialect: postgresDialect,
+    calls,
+    async execute(query) {
+      const call = calls.length;
+      calls.push(query);
+      return answer(query, call);
+    },
+  };
+}