@ultimat3/db 29.3.2 → 30.0.0

package/src/column-alter.ts

@@ -26,6 +26,47 @@ function screened(column: string, expression: string): string {
   return expression;
 }
 
+/** What the column should hold as a default: one this generator cannot render stays as it is. */
+export function wantedDefault(
+  column: ColumnDescriptionLike,
+  recorded: ColumnDescription,
+): string | null {
+  return hasUnrenderedDefault(column) ? recorded.default : defaultExpression(column);
+}
+
+/**
+ * The ALTER of a retype, with the column's default out of its way. Postgres converts a default with
+ * the column and refuses when no assignment cast exists (`42804`), whatever the new default is, so
+ * it is dropped first and set after: a type change is the one move that has to span the default.
+ * `down` is reversed at assembly, so what it pushes here runs last to first: drop the new default,
+ * retype back, restore the old one. With no default on either side, this is the bare ALTER.
+ */
+export function retypeOverDefault(
+  table: string,
+  column: ColumnDescriptionLike,
+  recorded: ColumnDescription,
+  plan: Plan,
+  up: string,
+  down: string,
+): void {
+  const alter = `alter table ${identifier(table).text} alter column ${identifier(column.column).text}`;
+  const drop = `${alter} drop default;`;
+  const set = (expression: string): string =>
+    `${alter} set default ${screened(column.column, expression)};`;
+  const wanted = wantedDefault(column, recorded);
+  const held = recorded.default;
+  if (held !== null) {
+    plan.up.push(drop);
+    plan.down.push(set(held));
+  }
+  plan.up.push(up);
+  plan.down.push(down);
+  if (wanted !== null) {
+    plan.up.push(set(wanted));
+    plan.down.push(drop);
+  }
+}
+
 /**
  * `set default` / `drop default` and `drop not null`, each with its reverse in `down` — the shape
  * `redefineIndex` (`index-ddl.ts`) gives a moved index. Becoming NOT NULL is deliberately NOT a
@@ -45,7 +86,7 @@ export function alterColumnInPlace(
 ): void {
   const { table } = entity;
   const alter = `alter table ${identifier(table).text} alter column ${identifier(column.column).text}`;
-  const wanted = hasUnrenderedDefault(column) ? recorded.default : defaultExpression(column);
+  const wanted = wantedDefault(column, recorded);
   const held = recorded.default;
   if (wanted !== held) {
     const set = (expression: string | null): string =>

package/src/concurrent-index.ts

@@ -0,0 +1,157 @@
+// Single responsibility: what makes a migration NON-TRANSACTIONAL, and which of its statements are
+// the concurrent index builds that need it. `create index concurrently` and `drop index
+// concurrently` are refused inside a transaction block (`25001`), so the one marker line below is
+// how a migration says "run me statement by statement, outside one" — read by `migration-step.ts`.
+
+import { hasMarkerLine } from './marker-line';
+import { IDENTIFIER_CHAR, noiseAt } from './sql-scan';
+import { sqlState } from './sqlstate';
+import { statementsOf } from './statement-split';
+
+/**
+ * The line a migration carries to run outside a transaction. Written into `up` by `x db gen` for
+ * the step that holds every concurrent index build, and it governs BOTH halves of the file: the
+ * `down` of a concurrent build is a concurrent drop, refused inside a transaction just the same.
+ */
+export const NO_TRANSACTION_MARKER = '-- transaction: false';
+
+/** The whole comment, as `-- destructive: true` is matched: a mention declares nothing. */
+const MARKER_COMMENT = /^--[ \t]*transaction:[ \t]*false[ \t]*\r?\n?$/i;
+
+/** Whether this migration's `up` declares it runs outside a transaction. */
+export const isNonTransactional = (up: string): boolean => hasMarkerLine(up, MARKER_COMMENT);
+
+interface Token {
+  readonly text: string;
+  /** A word to compare, lower-cased — `undefined` for a quoted identifier or a punctuation mark. */
+  readonly word: string | undefined;
+}
+
+const WHITESPACE = /\s/;
+
+/**
+ * The first `limit` tokens of one statement: comments skipped, a quoted identifier kept whole and
+ * verbatim, a literal or dollar body ending the read — no statement this file recognises has one
+ * before the name it is after. `sql-scan.ts` is the lexer, so a `"create"` is a name and not a verb.
+ */
+function leadingTokens(statement: string, limit: number): readonly Token[] {
+  const tokens: Token[] = [];
+  let index = 0;
+  while (index < statement.length && tokens.length < limit) {
+    const noise = noiseAt(statement, index);
+    if (noise !== null) {
+      if (noise.kind === 'string' || noise.kind === 'dollar-body') break;
+      if (noise.kind === 'identifier') {
+        tokens.push({ text: statement.slice(index, noise.end), word: undefined });
+      }
+      index = noise.end;
+      continue;
+    }
+    const char = statement[index] ?? '';
+    if (WHITESPACE.test(char)) {
+      index += 1;
+      continue;
+    }
+    let end = index + 1;
+    if (IDENTIFIER_CHAR.test(char)) {
+      while (end < statement.length && IDENTIFIER_CHAR.test(statement[end] ?? '')) end += 1;
+    }
+    const text = statement.slice(index, end);
+    tokens.push({ text, word: IDENTIFIER_CHAR.test(char) ? text.toLowerCase() : undefined });
+    index = end;
+  }
+  return tokens;
+}
+
+/**
+ * The index a `create [unique] index concurrently [if not exists] <name>` builds, spelled exactly
+ * as the statement spells it (`"runs_status_idx"`, `public.runs_status_idx`) — the text
+ * `to_regclass()` resolves and `drop index concurrently if exists` accepts. `null` for every other
+ * statement, and for an unnamed build: Postgres picks that name, so there is nothing to look up.
+ */
+export function concurrentIndexTarget(statement: string): string | null {
+  const tokens = leadingTokens(statement, 12);
+  const word = (at: number): string | undefined => tokens[at]?.word;
+  let at = 0;
+  if (word(at) !== 'create') return null;
+  at += word(at + 1) === 'unique' ? 2 : 1;
+  if (word(at) !== 'index' || word(at + 1) !== 'concurrently') return null;
+  at += 2;
+  if (word(at) === 'if' && word(at + 1) === 'not' && word(at + 2) === 'exists') at += 3;
+  const name = tokens[at];
+  if (name === undefined || name.word === 'on') return null;
+  const dot = tokens[at + 1];
+  const tail = tokens[at + 2];
+  if (dot?.text === '.' && tail !== undefined) return `${name.text}.${tail.text}`;
+  return name.text;
+}
+
+/**
+ * Whether one statement is an index build or drop Postgres refuses inside a transaction block:
+ * `create [unique] index concurrently`, `drop index concurrently`, `reindex … concurrently`.
+ */
+export function isConcurrentIndexStatement(statement: string): boolean {
+  const words = leadingTokens(statement, 8).map((token) => token.word);
+  const [first, second, third, fourth] = words;
+  if (first === 'create') {
+    return second === 'unique'
+      ? third === 'index' && fourth === 'concurrently'
+      : second === 'index' && third === 'concurrently';
+  }
+  if (first === 'drop') return second === 'index' && third === 'concurrently';
+  return first === 'reindex' && reindexIsConcurrent(statement);
+}
+
+/** `feature_not_supported` — what Postgres answers a concurrent build on a partitioned parent. */
+const FEATURE_NOT_SUPPORTED = '0A000';
+
+/**
+ * Whether `error` is Postgres refusing THIS statement as a concurrent build on a partitioned table:
+ * a `create [unique] index concurrently` answered `0A000`. Read off the SQLSTATE, never the
+ * message, which follows the server's `lc_messages`. `migration-step.ts` turns it into
+ * `X_MIGRATION_CONCURRENT_PARTITIONED`, whose fix is the sequence that replaces the build.
+ */
+export function isPartitionedBuildRefusal(statement: string, error: unknown): boolean {
+  const [first, second, third, fourth] = leadingTokens(statement, 4).map((token) => token.word);
+  const build =
+    first === 'create' &&
+    (second === 'unique'
+      ? third === 'index' && fourth === 'concurrently'
+      : second === 'index' && third === 'concurrently');
+  return build && sqlState(error) === FEATURE_NOT_SUPPORTED;
+}
+
+/** The values that switch a boolean `REINDEX` option OFF — Postgres' own spellings of false. */
+const OFF = new Set(['false', 'off', '0', 'no']);
+
+/**
+ * `REINDEX [ ( option [, …] ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURRENTLY ] name`
+ * — read whole, never through a fixed window: the option list has no length bound, and
+ * `CONCURRENTLY [ boolean ]` may itself be one of the options.
+ */
+function reindexIsConcurrent(statement: string): boolean {
+  const tokens = leadingTokens(statement, Number.POSITIVE_INFINITY);
+  let at = 1;
+  if (tokens[at]?.text === '(') {
+    let option: (string | undefined)[] = [];
+    const settle = (): boolean => option[0] === 'concurrently' && !OFF.has(option[1] ?? '');
+    for (at += 1; at < tokens.length; at += 1) {
+      const text = tokens[at]?.text;
+      if (text === ')' || text === ',') {
+        if (settle()) return true;
+        option = [];
+        if (text === ')') break;
+        continue;
+      }
+      option.push(tokens[at]?.word);
+    }
+    at += 1;
+  }
+  // The object kind, then the modifier — never the name after it, so `index "concurrently"` and
+  // `index concurrently_idx` are not concurrent.
+  return tokens[at + 1]?.word === 'concurrently';
+}
+
+/** The first statement of `script` that cannot run inside a transaction, or `undefined`. */
+export const firstConcurrentStatement = (script: string): string | undefined =>
+  statementsOf(script).find(isConcurrentIndexStatement);

package/src/concurrent-plan.ts

@@ -0,0 +1,294 @@
+// Single responsibility: the work `x db gen` moves OUT of the migration's transaction into a step
+// of its own — `concurrently: true` builds and index removals (`index-plan.ts` decides which), plus
+// live-table foreign keys and CHECK validation (`foreign-key-plan.ts`, `check-ddl.ts`), each an
+// outage under a lock that stops writes. It writes the statements and the intermediate snapshot.
+
+import type { IndexDescriptionLike } from './entity-shape';
+import {
+  dropForeignKeyIfExists,
+  replaceForeignKeyNotValid,
+  validateConstraint,
+} from './foreign-key';
+import type { Plan } from './foreign-key-plan';
+import {
+  asDeclared,
+  createIndex,
+  dropIndexConcurrently,
+  indexShape,
+  mayBeConstraintBacked,
+} from './index-ddl';
+import type { ForeignKeyDescription, IndexDescription, SchemaDescription } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * One index the non-transactional step changes: `recorded` is what stood there before it (absent
+ * for a new build) — what the transactional step's snapshot still records (`intermediateSnapshot`).
+ */
+export interface DeferredIndex {
+  readonly table: string;
+  readonly name: string;
+  readonly recorded?: IndexDescription | undefined;
+  /**
+   * What the step builds, absent for a removal: a foreign key over exactly these columns cannot be
+   * added before the step, or the transactional step answers `42830` (`targetIndexDeferred`).
+   */
+  readonly builds?: { readonly columns: readonly string[]; readonly unique: boolean } | undefined;
+}
+
+/**
+ * One key the non-transactional step changes: `recorded` is what the transactional step's snapshot
+ * still records under this name (absent for a new key). The `DeferredIndex` of a constraint, and
+ * for the same reason: a failed second step must not leave a ledger claiming a key the catalog lacks.
+ */
+export interface DeferredKey {
+  readonly table: string;
+  readonly name: string;
+  readonly recorded?: ForeignKeyDescription | undefined;
+}
+
+/**
+ * The non-transactional step's statements, in phases, and what each changes for the snapshot.
+ * `up`/`down` EXPAND (every build), `keys` adds each key `not valid`, `validate` scans the rows they
+ * let stand, and `contractKeys` then `contract` CONTRACT (every removal): each phase finishes before
+ * the next starts, so a replacement exists before what it replaces goes — across tables too, since
+ * the phases are joined once, at assembly (`stepStatements`).
+ */
+export interface ConcurrentPlan extends Plan {
+  readonly contract: string[];
+  readonly contractDown: string[];
+  readonly deferred: DeferredIndex[];
+  readonly keys: string[];
+  readonly keysDown: string[];
+  readonly validate: string[];
+  /** A dropped key goes before a dropped index: the key may be what still needs that index. */
+  readonly contractKeys: string[];
+  readonly contractKeysDown: string[];
+  readonly deferredKeys: DeferredKey[];
+}
+
+export const emptyConcurrentPlan = (): ConcurrentPlan => ({
+  up: [],
+  down: [],
+  contract: [],
+  contractDown: [],
+  deferred: [],
+  keys: [],
+  keysDown: [],
+  validate: [],
+  contractKeys: [],
+  contractKeysDown: [],
+  deferredKeys: [],
+});
+
+/**
+ * The step's script in apply order — index builds, key adds, validates, contract — and its reversal:
+ * what was removed is restored FIRST, then what is new dropped, so the reversal has no gap either.
+ * A `validate` has no reversal: un-validating a constraint nobody asked to weaken undoes nothing.
+ */
+export function stepStatements(plan: ConcurrentPlan): {
+  readonly up: readonly string[];
+  readonly down: readonly string[];
+} {
+  return {
+    up: [...plan.up, ...plan.keys, ...plan.validate, ...plan.contractKeys, ...plan.contract],
+    down: [
+      ...plan.down,
+      ...plan.keysDown,
+      ...plan.contractKeysDown,
+      ...plan.contractDown,
+    ].reverse(),
+  };
+}
+
+/** A declared index this migration builds new, concurrently, with its concurrent drop as `down`. */
+export function buildConcurrently(
+  table: string,
+  index: IndexDescriptionLike,
+  concurrent: ConcurrentPlan,
+): void {
+  concurrent.up.push(createIndex(table, index, true));
+  concurrent.down.push(dropIndexConcurrently(index.name));
+  concurrent.deferred.push({ table, name: index.name, builds: builtBy(index) });
+}
+
+const builtBy = (index: IndexDescriptionLike): NonNullable<DeferredIndex['builds']> => ({
+  columns: index.columns,
+  unique: index.unique,
+});
+
+/**
+ * Whether the unique index a key over `columns` of `table` needs is one this step builds. Column
+ * sets, not lists: Postgres matches a key to a unique index whichever way round either spells them.
+ */
+export function targetIndexDeferred(
+  concurrent: ConcurrentPlan,
+  table: string,
+  columns: readonly string[],
+): boolean {
+  const wanted = new Set(columns);
+  return concurrent.deferred.some(
+    ({ table: owner, builds }) =>
+      owner === table &&
+      builds?.unique === true &&
+      builds.columns.length === wanted.size &&
+      builds.columns.every((column) => wanted.has(column)),
+  );
+}
+
+/**
+ * Add a key without stopping writes: `not valid` then `validate`, both in the deferred step.
+ * `recorded` is the key this one replaces under the SAME name, which the one ALTER swaps with no
+ * gap; a key under another name stays up until `contractKey`, in the contract phase.
+ */
+export function deferKey(
+  table: string,
+  key: ForeignKeyDescription,
+  recorded: ForeignKeyDescription | undefined,
+  concurrent: ConcurrentPlan,
+): void {
+  concurrent.keys.push(replaceForeignKeyNotValid(table, key));
+  concurrent.validate.push(validateConstraint(table, key.name));
+  // Pushed forwards and read backwards, like every `down`: the rebuild lands before its validate.
+  if (recorded === undefined) {
+    concurrent.keysDown.push(dropForeignKeyIfExists(table, key.name));
+  } else {
+    concurrent.keysDown.push(
+      validateConstraint(table, key.name),
+      replaceForeignKeyNotValid(table, recorded),
+    );
+  }
+  concurrent.deferredKeys.push({ table, name: key.name, recorded });
+}
+
+/** A recorded key the step's new keys replace: dropped last, restored first on the way back. */
+export function contractKey(
+  table: string,
+  recorded: ForeignKeyDescription,
+  concurrent: ConcurrentPlan,
+): void {
+  concurrent.contractKeys.push(dropForeignKeyIfExists(table, recorded.name));
+  concurrent.contractKeysDown.push(
+    validateConstraint(table, recorded.name),
+    replaceForeignKeyNotValid(table, recorded),
+  );
+  concurrent.deferredKeys.push({ table, name: recorded.name, recorded });
+}
+
+/** A constraint the transaction added `not valid`: its scan runs here, after the commit. */
+export function deferValidate(table: string, name: string, concurrent: ConcurrentPlan): void {
+  concurrent.validate.push(validateConstraint(table, name));
+}
+
+/**
+ * Drop a RECORDED index whose kind this generator cannot know, in statements that are correct on
+ * both databases it cannot tell apart.
+ *
+ * `TableDescription` carries no discriminator, and it cannot be given one that would help: the
+ * SAME declaration reaches the server as a CONSTRAINT or as an INDEX depending on which migration
+ * created it. A `unique` column on a table `createTable` writes emits `create table … slug text
+ * unique`, and Postgres backs that with a constraint named `posts_slug_key`; the same column
+ * gaining `unique` later takes `create unique index "posts_slug_key"` and is a plain index.
+ * `snapshotOf` records both as `{ unique: true, primary: false }`.
+ *
+ * Measured on 18.4 (`index-removal.live.test.ts`), which is why the pair and not a guess:
+ *
+ * | statement                                    | on a constraint's index    | on a plain index |
+ * |----------------------------------------------|----------------------------|------------------|
+ * | `drop index [if exists] "n"`                 | **2BP01** — not suppressed | ok               |
+ * | `drop index concurrently if exists "n"`      | **2BP01** — not suppressed | ok               |
+ * | `alter table … drop constraint if exists`    | drops it, index and all    | notice, no-op    |
+ *
+ * So the shape `mayBeConstraintBacked` cannot rule out is first unhooked by the ALTER, and the
+ * concurrent drop after it is then a no-op notice or the whole job. Constraint first: reversed,
+ * the drop reaches a constraint's index and is the 2BP01 this exists to avoid.
+ *
+ * Both in the SAME non-transactional step, and in the phase `into` names. Never the ALTER in the
+ * transactional step before it: that step's `down` cannot restore a constraint, so a rollback after
+ * a failed concurrent step left the table with no uniqueness at all — and it would unhook the old
+ * key before a concurrent replacement existed, letting in the duplicates that then fail its build.
+ * The ALTER takes ACCESS EXCLUSIVE, so the runner gives a statement like it a transaction of its
+ * own under `lock_timeout` (`migration-step.ts`); the concurrent drop stays unbounded.
+ */
+function dropRecordedConcurrently(table: string, recorded: IndexDescription, into: string[]): void {
+  if (mayBeConstraintBacked(recorded)) {
+    into.push(
+      `alter table ${identifier(table).text} drop constraint if exists ${identifier(recorded.name).text};`,
+    );
+  }
+  into.push(dropIndexConcurrently(recorded.name));
+}
+
+/**
+ * A recorded index no entity declares any more: dropped concurrently, and restored by `down` —
+ * concurrently too — from what the SNAPSHOT recorded, never from the entity that stopped declaring it.
+ */
+export function removeConcurrently(
+  table: string,
+  recorded: IndexDescription,
+  concurrent: ConcurrentPlan,
+): void {
+  dropRecordedConcurrently(table, recorded, concurrent.contract);
+  concurrent.contractDown.push(createIndex(table, asDeclared(recorded), true));
+  concurrent.deferred.push({ table, name: recorded.name, recorded });
+}
+
+/**
+ * A `concurrently: true` index whose definition moved: dropped and rebuilt, both concurrently —
+ * `redefineIndex`'s pair outside the transaction. Between the two statements the table has neither
+ * definition; for a unique index that is a window with no uniqueness, the price of never blocking a
+ * write (name the new shape differently to build it beside the old one instead).
+ */
+export function redefineConcurrently(
+  table: string,
+  index: IndexDescriptionLike,
+  recorded: IndexDescription,
+  concurrent: ConcurrentPlan,
+): void {
+  if (indexShape(index) === indexShape(recorded)) return;
+  // One name, so no expand → contract is possible: the drop must precede the build, in the
+  // expand phase, in that order.
+  dropRecordedConcurrently(table, recorded, concurrent.up);
+  concurrent.up.push(createIndex(table, index, true));
+  // Pushed forwards and read backwards, as `redefineIndex`'s: the recorded definition lands last.
+  concurrent.down.push(
+    createIndex(table, asDeclared(recorded), true),
+    dropIndexConcurrently(index.name),
+  );
+  concurrent.deferred.push({ table, name: index.name, recorded, builds: builtBy(index) });
+}
+
+/**
+ * The schema the TRANSACTIONAL step leaves behind when a non-transactional one follows it: the
+ * final snapshot with every deferred index put back the way it was — gone if it is new, its
+ * recorded definition if it is removed or rebuilt. The sidecar is "the schema this migration leaves
+ * behind", and a database that applied the first step alone holds exactly this: the first step
+ * removes no index and unhooks no constraint, so every recorded one is still there. A deferred key
+ * reads the same way: lacking while new, its recorded definition while replaced or contracted.
+ */
+export function intermediateSnapshot(
+  final: SchemaDescription,
+  deferred: readonly DeferredIndex[],
+  deferredKeys: readonly DeferredKey[] = [],
+): SchemaDescription {
+  return {
+    ...final,
+    tables: final.tables.map((table) => {
+      const mine = deferred.filter((each) => each.table === table.name);
+      const keys = deferredKeys.filter((each) => each.table === table.name);
+      if (mine.length === 0 && keys.length === 0) return table;
+      const names = new Set(mine.map((each) => each.name));
+      const keyNames = new Set(keys.map((each) => each.name));
+      return {
+        ...table,
+        indexes: [
+          ...table.indexes.filter((index) => !names.has(index.name)),
+          ...mine.flatMap((each) => (each.recorded === undefined ? [] : [each.recorded])),
+        ],
+        foreignKeys: [
+          ...table.foreignKeys.filter((key) => !keyNames.has(key.name)),
+          ...keys.flatMap((each) => (each.recorded === undefined ? [] : [each.recorded])),
+        ].sort((a, b) => (a.name < b.name ? -1 : 1)),
+      };
+    }),
+  };
+}

package/src/connection-url.ts

@@ -6,10 +6,13 @@ import { describeValue } from '@ultimat3/core';
 import { DbError, dbUnavailable } from './errors';
 import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
 import type { PoolProfile } from './pool-profile';
+import type { PoolerMode } from './pooler';
 
 export interface ConnectionUrlOptions {
   readonly url?: string | undefined;
   readonly applicationName?: string | undefined;
+  /** A pooler in the path: the bounds are the server's (`alter role`), and `options` carries none. */
+  readonly pooler?: PoolerMode | undefined;
 }
 
 /**
@@ -85,9 +88,15 @@ export function connectionUrl(options: ConnectionUrlOptions, profile: PoolProfil
   // is silent. Both spellings count, or the URL parameter and a `-c application_name=` in
   // `options` disagree and which one the backend honours is argument order nobody here measured.
   const named = options.applicationName;
-  const settings: Record<string, string> = {
-    statement_timeout: String(profile.statementTimeoutMs),
-  };
+  // A pooler refuses these at startup or drops them in silence, so with one named neither is sent
+  // and the bound moves to `alter role`, applied at the pooler's own server login.
+  const settings: Record<string, string> =
+    options.pooler === undefined
+      ? {
+          statement_timeout: String(profile.statementTimeoutMs),
+          idle_in_transaction_session_timeout: String(profile.idleInTransactionMs),
+        }
+      : {};
   const inOptions = declaresLibpqOption(url.searchParams.get('options'), 'application_name');
   // An explicit `applicationName` is a deliberate call by the role that opened the pool, so it
   // wins. Only then is the setting named to the merge, and only when the operator wrote the other
@@ -95,7 +104,10 @@ export function connectionUrl(options: ConnectionUrlOptions, profile: PoolProfil
   // disagree — and a URL with no assignment in it keeps the exact `options` it always had.
   if (named !== undefined && inOptions) settings['application_name'] = named;
   const declared = url.searchParams.has('application_name') || inOptions;
-  url.searchParams.set('options', mergeLibpqOptions(url.searchParams.get('options'), settings));
+  const merged = mergeLibpqOptions(url.searchParams.get('options'), settings);
+  // An empty `options` is a parameter all the same, and it is the parameter a pooler is asked about.
+  if (merged === '') url.searchParams.delete('options');
+  else url.searchParams.set('options', merged);
   if (named !== undefined) url.searchParams.set('application_name', named);
   else if (!declared) url.searchParams.set('application_name', 'ultimate');
   return url.toString();

package/src/db-diagnostics-deadline.ts

@@ -0,0 +1,43 @@
+// Single responsibility: stop WAITING for a diagnostic read the server never answers. PGlite applies
+// `statement_timeout` and cannot fire it mid-scan, so on the embedded database the 2 s bound is no
+// bound; this one is the client's, and it abandons the wait, not the statement.
+
+import type { Scheduler } from '@ultimat3/core';
+
+/** What `within` answers when the deadline came first. */
+export const EXPIRED: unique symbol = Symbol('diagnostics.expired');
+
+/**
+ * `work`'s answer, or `EXPIRED` once `ms` pass. A rejection arriving after the deadline is
+ * handled here, never left unhandled; the statement itself runs on until its driver ends it.
+ */
+export async function within<T>(
+  work: Promise<T>,
+  ms: number,
+  schedule: Scheduler,
+): Promise<T | typeof EXPIRED> {
+  let cancel: () => void = () => undefined;
+  const expired = new Promise<typeof EXPIRED>((resolve) => {
+    cancel = schedule(() => resolve(EXPIRED), ms);
+  });
+  work.catch(() => undefined);
+  try {
+    return await Promise.race([work, expired]);
+  } finally {
+    cancel();
+  }
+}
+
+/** A deadline that, once passed, stays passed: the whole command's budget. */
+export interface CommandDeadline {
+  passed(): boolean;
+  release(): void;
+}
+
+export function commandDeadline(ms: number, schedule: Scheduler): CommandDeadline {
+  let passed = false;
+  const cancel = schedule(() => {
+    passed = true;
+  }, ms);
+  return { passed: () => passed, release: cancel };
+}

package/src/db-diagnostics-redact.ts

@@ -0,0 +1,58 @@
+// Single responsibility: a session's SQL text reduced to its shape before `x db diagnostics` prints
+// it. `pg_stat_activity.query` is the text a client sent, literals and all, so a row value an
+// unparameterised statement carried would otherwise reach a terminal, a log or an agent.
+
+import { noiseAt } from './sql-scan';
+
+/** Characters kept after redaction: enough to recognise a statement, never a whole report. */
+export const QUERY_TEXT_MAX = 300;
+
+/** Digits with Postgres 16's `_` separators between them (`1_234_567`). */
+const DIGITS = String.raw`\d(?:_?\d)*`;
+
+/**
+ * A numeric literal standing alone: not part of a name (`t1`), not a placeholder (`$1`), not a
+ * type modifier read off an identifier (`int4`). Lookbehind keeps the preceding character. The
+ * Postgres 16 spellings are one literal each: `0x`/`0o`/`0b` with any digits and `_` after it,
+ * and `_` between digits in the whole, fractional and exponent parts.
+ */
+const NUMERIC = new RegExp(
+  String.raw`(?<![A-Za-z0-9_$."])(?:0[xob][0-9a-f_]+|(?:${DIGITS}(?:\.(?:${DIGITS})?)?|\.${DIGITS})(?:e[+-]?${DIGITS})?)`,
+  'gi',
+);
+
+/**
+ * Literals (string, escape string, dollar-quoted, numeric) become `?`, comments go, quoted
+ * identifiers and `$n` placeholders stay. Walked with `sql-scan.ts`'s `noiseAt`, the package's one
+ * lexer, so a `--` inside a literal is data here exactly as it is to the destructive rail. A
+ * literal the server truncated mid-way runs to the end of the text and is redacted whole.
+ */
+export function redactQueryText(text: string): string {
+  let out = '';
+  let plain = '';
+  const flush = (): void => {
+    out += plain.replace(NUMERIC, '?');
+    plain = '';
+  };
+  let index = 0;
+  while (index < text.length) {
+    const noise = noiseAt(text, index);
+    if (noise === null) {
+      plain += text[index];
+      index += 1;
+      continue;
+    }
+    flush();
+    if (noise.kind === 'identifier') out += text.slice(index, noise.end);
+    else if (noise.kind === 'string' || noise.kind === 'dollar-body') out += '?';
+    else out += ' ';
+    index = noise.end;
+  }
+  flush();
+  // An escape-string prefix (`E'…'`, `X'…'`) is left as a lone letter before its `?`.
+  const shaped = out
+    .replace(/(?<![A-Za-z0-9_$])[ebxun]&?\?/gi, '?')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return shaped.length > QUERY_TEXT_MAX ? `${shaped.slice(0, QUERY_TEXT_MAX)}…` : shaped;
+}