@ultimat3/db 29.3.2 → 30.0.0

package/src/db-diagnostics-rows.ts

@@ -0,0 +1,166 @@
+// Single responsibility: one catalog row, as the driver handed it, into `dbDiagnostics`' typed
+// row. Column names stay the SQL's (`db-diagnostics-sql.ts`); the fields are what `--json` prints.
+// The two drivers disagree on `int8` (text, bigint or number), so every count is read here, once.
+
+type Raw = Readonly<Record<string, unknown>>;
+type Redact = (text: string) => string;
+
+/** A count or an age in seconds, whichever type the driver chose; `null` when the server had none. */
+const count = (value: unknown): number | null => {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+};
+
+const text = (value: unknown): string | null => (typeof value === 'string' ? value : null);
+
+const flag = (value: unknown): boolean | null => (typeof value === 'boolean' ? value : null);
+
+/** Statement text, shaped by the caller's redactor: never sent out as the server stored it. */
+const statement = (value: unknown, redact: Redact): string | null => {
+  const raw = text(value);
+  return raw === null ? null : redact(raw);
+};
+
+export interface BlockerRow {
+  readonly pid: number | null;
+  readonly blockedBy: number | null;
+  readonly waitEventType: string | null;
+  readonly waitEvent: string | null;
+  readonly waitingSeconds: number | null;
+  readonly query: string | null;
+  readonly blockerState: string | null;
+  readonly blockerTransactionSeconds: number | null;
+  readonly blockerQuery: string | null;
+}
+
+export const blockerRow = (raw: Raw, redact: Redact): BlockerRow => ({
+  pid: count(raw['pid']),
+  blockedBy: count(raw['blocked_by']),
+  waitEventType: text(raw['wait_event_type']),
+  waitEvent: text(raw['wait_event']),
+  waitingSeconds: count(raw['waiting_seconds']),
+  query: statement(raw['query'], redact),
+  blockerState: text(raw['blocker_state']),
+  blockerTransactionSeconds: count(raw['blocker_transaction_seconds']),
+  blockerQuery: statement(raw['blocker_query'], redact),
+});
+
+export interface ActivityRow {
+  readonly pid: number | null;
+  readonly role: string | null;
+  readonly applicationName: string | null;
+  readonly state: string | null;
+  readonly waitEventType: string | null;
+  readonly waitEvent: string | null;
+  readonly transactionSeconds: number | null;
+  readonly querySeconds: number | null;
+  /** False when this role lacks `pg_read_all_stats` for that session: a fact, not an error. */
+  readonly queryVisible: boolean;
+  readonly query: string | null;
+}
+
+export const activityRow = (raw: Raw, redact: Redact): ActivityRow => {
+  const queryVisible = flag(raw['query_visible']) ?? false;
+  return {
+    pid: count(raw['pid']),
+    role: text(raw['role']),
+    applicationName: text(raw['application_name']),
+    state: text(raw['state']),
+    waitEventType: text(raw['wait_event_type']),
+    waitEvent: text(raw['wait_event']),
+    transactionSeconds: count(raw['transaction_seconds']),
+    querySeconds: count(raw['query_seconds']),
+    queryVisible,
+    query: queryVisible ? statement(raw['query'], redact) : null,
+  };
+};
+
+export interface SlowQueryRow {
+  readonly queryId: string | null;
+  readonly calls: number | null;
+  readonly totalMs: number | null;
+  readonly meanMs: number | null;
+  readonly rows: number | null;
+  readonly query: string | null;
+}
+
+export const slowQueryRow = (raw: Raw, redact: Redact): SlowQueryRow => ({
+  queryId: text(raw['query_id']),
+  calls: count(raw['calls']),
+  totalMs: count(raw['total_ms']),
+  meanMs: count(raw['mean_ms']),
+  rows: count(raw['rows']),
+  query: statement(raw['query'], redact),
+});
+
+export interface UnusedIndexRow {
+  readonly schema: string | null;
+  readonly table: string | null;
+  readonly index: string | null;
+  readonly sizeBytes: number | null;
+  /** Seconds since this database's counters were reset; `null` = never reset. */
+  readonly statsAgeSeconds: number | null;
+  /** Counters are per server: a replica's zero says nothing of the primary's scans. */
+  readonly replica: boolean | null;
+}
+
+export const unusedIndexRow = (raw: Raw): UnusedIndexRow => ({
+  schema: text(raw['schema']),
+  table: text(raw['table_name']),
+  index: text(raw['index_name']),
+  sizeBytes: count(raw['size_bytes']),
+  statsAgeSeconds: count(raw['stats_age_seconds']),
+  replica: flag(raw['replica']),
+});
+
+export interface InvalidIndexRow {
+  readonly schema: string | null;
+  readonly table: string | null;
+  readonly index: string | null;
+}
+
+export const invalidIndexRow = (raw: Raw): InvalidIndexRow => ({
+  schema: text(raw['schema']),
+  table: text(raw['table_name']),
+  index: text(raw['index_name']),
+});
+
+export interface NotValidConstraintRow {
+  readonly schema: string | null;
+  readonly table: string | null;
+  readonly constraint: string | null;
+  /** `check`, `foreign-key`, or Postgres' own one-letter `contype` for anything else. */
+  readonly kind: string | null;
+}
+
+export const notValidConstraintRow = (raw: Raw): NotValidConstraintRow => ({
+  schema: text(raw['schema']),
+  table: text(raw['table_name']),
+  constraint: text(raw['constraint_name']),
+  kind: text(raw['kind']),
+});
+
+export interface DeadTupleRow {
+  readonly schema: string | null;
+  readonly table: string | null;
+  readonly live: number | null;
+  readonly dead: number | null;
+  readonly autovacuumAgeSeconds: number | null;
+  readonly vacuumAgeSeconds: number | null;
+  readonly analyzeAgeSeconds: number | null;
+}
+
+export const deadTupleRow = (raw: Raw): DeadTupleRow => ({
+  schema: text(raw['schema']),
+  table: text(raw['table_name']),
+  live: count(raw['live']),
+  dead: count(raw['dead']),
+  autovacuumAgeSeconds: count(raw['autovacuum_age_seconds']),
+  vacuumAgeSeconds: count(raw['vacuum_age_seconds']),
+  analyzeAgeSeconds: count(raw['analyze_age_seconds']),
+});

package/src/db-diagnostics-sql.ts

@@ -0,0 +1,92 @@
+// Single responsibility: the seven catalog reads behind `dbDiagnostics`, one constant statement
+// each. Catalog and statistics views only — no statement here reads a user table, so no row value
+// can be in an answer; the one free text (`query`) is redacted by the caller before it leaves.
+
+/** Every database name filter is `current_database()`: a shared server's other tenants are not ours. */
+const OUR_DATABASE = 'datname = current_database()';
+
+/** Waiting sessions and the pid each one waits on, longest wait first. */
+export const BLOCKERS_SQL = `select w.pid as pid, b.pid as blocked_by, w.wait_event_type as wait_event_type,
+  w.wait_event as wait_event, round(extract(epoch from now() - w.query_start))::int as waiting_seconds,
+  w.query as query, b.state as blocker_state,
+  round(extract(epoch from now() - b.xact_start))::int as blocker_transaction_seconds,
+  b.query as blocker_query
+from pg_stat_activity w
+cross join lateral unnest(pg_blocking_pids(w.pid)) as blocker(pid)
+join pg_stat_activity b on b.pid = blocker.pid
+where w.${OUR_DATABASE}
+order by waiting_seconds desc nulls last, w.pid`;
+
+/**
+ * Every client session that is not idle, oldest transaction first. A session another role owns
+ * reads `<insufficient privilege>` without `pg_read_all_stats`: reported as `query_visible`.
+ */
+export const ACTIVITY_SQL = `select pid, usename as role, application_name, state,
+  wait_event_type, wait_event,
+  round(extract(epoch from now() - xact_start))::int as transaction_seconds,
+  round(extract(epoch from now() - query_start))::int as query_seconds,
+  query is distinct from '<insufficient privilege>' as query_visible, query
+from pg_stat_activity
+where ${OUR_DATABASE} and pid <> pg_backend_pid() and backend_type = 'client backend'
+  and coalesce(state, '') <> 'idle'
+order by xact_start nulls last, pid`;
+
+/**
+ * `pg_stat_statements` is an extension: on a server without it this is `42P01` and the section is
+ * reported unavailable. Its text is what the server normalised; the caller redacts it anyway, since
+ * a utility statement is stored as sent.
+ */
+export const SLOW_QUERIES_SQL = `select queryid::text as query_id, calls,
+  round(total_exec_time::numeric, 1)::float8 as total_ms,
+  round(mean_exec_time::numeric, 2)::float8 as mean_ms, rows, query
+from pg_stat_statements
+where dbid = (select oid from pg_database where ${OUR_DATABASE})
+order by total_exec_time desc`;
+
+/**
+ * Never scanned since the counters were reset. Unique and primary indexes are excluded: they
+ * enforce, and a scan count does not measure that. The counters' age and the server's recovery
+ * state ride on each row, because a count since yesterday, or on a replica, is not "unused".
+ */
+export const UNUSED_INDEXES_SQL = `select s.schemaname as schema, s.relname as table_name,
+  s.indexrelname as index_name, pg_relation_size(s.indexrelid) as size_bytes,
+  (select round(extract(epoch from now() - d.stats_reset))::int
+     from pg_stat_database d where d.${OUR_DATABASE}) as stats_age_seconds,
+  pg_is_in_recovery() as replica
+from pg_stat_user_indexes s
+join pg_index i on i.indexrelid = s.indexrelid
+where s.idx_scan = 0 and not i.indisunique and not i.indisprimary
+order by pg_relation_size(s.indexrelid) desc, s.indexrelname`;
+
+const USER_SCHEMA = (column: string): string =>
+  `${column} not in ('pg_catalog', 'information_schema') and ${column} not like 'pg\\_toast%'`;
+
+/** An index a failed `create index concurrently` left behind: written to, never read from. */
+export const INVALID_INDEXES_SQL = `select n.nspname as schema, t.relname as table_name,
+  c.relname as index_name
+from pg_index i
+join pg_class c on c.oid = i.indexrelid
+join pg_class t on t.oid = i.indrelid
+join pg_namespace n on n.oid = c.relnamespace
+where not i.indisvalid and ${USER_SCHEMA('n.nspname')}
+order by n.nspname, t.relname, c.relname`;
+
+/** Added `not valid` and never validated: new rows are checked, old ones are not. Names only. */
+export const NOT_VALID_CONSTRAINTS_SQL = `select n.nspname as schema, t.relname as table_name,
+  c.conname as constraint_name,
+  case c.contype when 'c' then 'check' when 'f' then 'foreign-key' else c.contype::text end as kind
+from pg_constraint c
+join pg_class t on t.oid = c.conrelid
+join pg_namespace n on n.oid = t.relnamespace
+where not c.convalidated and ${USER_SCHEMA('n.nspname')}
+order by n.nspname, t.relname, c.conname`;
+
+/** Counts and ages from the statistics collector; no estimate of bloat, which would be a guess. */
+export const DEAD_TUPLES_SQL = `select schemaname as schema, relname as table_name,
+  n_live_tup as live, n_dead_tup as dead,
+  round(extract(epoch from now() - last_autovacuum))::int as autovacuum_age_seconds,
+  round(extract(epoch from now() - greatest(last_vacuum, last_autovacuum)))::int as vacuum_age_seconds,
+  round(extract(epoch from now() - greatest(last_analyze, last_autoanalyze)))::int as analyze_age_seconds
+from pg_stat_user_tables
+where n_dead_tup > 0
+order by n_dead_tup desc, relname`;

package/src/db-diagnostics.ts

@@ -0,0 +1,178 @@
+// Single responsibility: `dbDiagnostics()` — what the database is doing right now (blockers,
+// activity, slow statements, unused and invalid indexes, unvalidated constraints, dead tuples), as
+// facts and never a verdict. `db-health.ts` stays the readiness probe `/readyz` reads.
+
+import { finiteCount, isUltimateError, renderThrowable, type Scheduler } from '@ultimat3/core';
+import type { DbClient } from './client';
+import { commandDeadline, EXPIRED, within } from './db-diagnostics-deadline';
+import { redactQueryText } from './db-diagnostics-redact';
+import {
+  type ActivityRow,
+  activityRow,
+  type BlockerRow,
+  blockerRow,
+  type DeadTupleRow,
+  deadTupleRow,
+  type InvalidIndexRow,
+  invalidIndexRow,
+  type NotValidConstraintRow,
+  notValidConstraintRow,
+  type SlowQueryRow,
+  slowQueryRow,
+  type UnusedIndexRow,
+  unusedIndexRow,
+} from './db-diagnostics-rows';
+import {
+  ACTIVITY_SQL,
+  BLOCKERS_SQL,
+  DEAD_TUPLES_SQL,
+  INVALID_INDEXES_SQL,
+  NOT_VALID_CONSTRAINTS_SQL,
+  SLOW_QUERIES_SQL,
+  UNUSED_INDEXES_SQL,
+} from './db-diagnostics-sql';
+import { dbUnavailable } from './errors';
+import { unrefSchedule } from './pool-timer';
+import { readOnlyQuery } from './readonly-query';
+
+/** Per statement. A catalog read that takes longer is itself the finding, reported as its section. */
+export const DIAGNOSTICS_TIMEOUT_MS = 2_000;
+/** Rows per section, fetched through a cursor so the server stops there. */
+export const DIAGNOSTICS_LIMIT = 20;
+/** The client's own wait per statement: the server's bound plus a second for the answer to land. */
+export const DIAGNOSTICS_SECTION_DEADLINE_MS = DIAGNOSTICS_TIMEOUT_MS + 1_000;
+/** The whole command. Past it, the sections not yet asked are reported unsent. */
+export const DIAGNOSTICS_DEADLINE_MS = 15_000;
+
+export interface DbDiagnosticsOptions {
+  /** Override the ambient pool. */
+  readonly client?: DbClient | undefined;
+  /** Rows per section; a whole number ≥ 1. Default `DIAGNOSTICS_LIMIT`. */
+  readonly limit?: number | undefined;
+  /** Arms both client-side deadlines. A seam for tests; default an unref'd `setTimeout`. */
+  readonly schedule?: Scheduler | undefined;
+}
+
+/** A section answered, or why it could not be and what would make it answer. Never a throw. */
+export type DiagnosticSection<Row> =
+  | { readonly available: true; readonly rows: readonly Row[] }
+  | {
+      readonly available: false;
+      readonly code: string;
+      readonly reason: string;
+      readonly fix: string;
+    };
+
+export interface DbDiagnostics {
+  readonly blockers: DiagnosticSection<BlockerRow>;
+  readonly activity: DiagnosticSection<ActivityRow>;
+  readonly slowQueries: DiagnosticSection<SlowQueryRow>;
+  readonly unusedIndexes: DiagnosticSection<UnusedIndexRow>;
+  readonly invalidIndexes: DiagnosticSection<InvalidIndexRow>;
+  readonly notValidConstraints: DiagnosticSection<NotValidConstraintRow>;
+  readonly deadTuples: DiagnosticSection<DeadTupleRow>;
+}
+
+/** An operator's act, in the database: this framework never creates an extension for the app. */
+export const SLOW_QUERIES_FIX =
+  `psql "$DATABASE_URL" -c 'create extension if not exists pg_stat_statements'` +
+  "   # after shared_preload_libraries = 'pg_stat_statements' in postgresql.conf and a server restart";
+
+/** A section the client stopped waiting for, or never sent: the server's own timeout code. */
+const TIMED_OUT = 'X_DB_STATEMENT_TIMEOUT';
+
+/** What a section without an `UltimateError` of its own hands out: the same read, by hand. */
+const GENERIC_FIX =
+  'x db diagnostics --json   # re-run once the load that timed this read out passes';
+
+/** `scheme://user:password@host` → `scheme://***@host`: a reason is printed, a credential never. */
+const scrubCredentials = (text: string): string =>
+  text.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@'"]*@/gi, '$1***@');
+
+/**
+ * Every section is one statement through `readOnlyQuery` — its own `BEGIN READ ONLY`, a 2 s
+ * `statement_timeout`, a cursor capped at `limit` — run one after another, so a diagnostic holds
+ * one connection and never seven. A section that fails is reported in place: one timeout does not
+ * lose the other six. The single throw is a probe that cannot open a connection at all.
+ */
+export async function dbDiagnostics(options: DbDiagnosticsOptions = {}): Promise<DbDiagnostics> {
+  const limit = finiteCount('dbDiagnostics', 'limit', options.limit ?? DIAGNOSTICS_LIMIT, 1);
+  const read = { client: options.client, timeoutMs: DIAGNOSTICS_TIMEOUT_MS } as const;
+  const schedule = options.schedule ?? unrefSchedule;
+  const sectionMs = DIAGNOSTICS_SECTION_DEADLINE_MS;
+  try {
+    const probe = await within(readOnlyQuery('select 1', read), sectionMs, schedule);
+    if (probe === EXPIRED) {
+      throw dbUnavailable(`x db diagnostics had no answer to select 1 within ${sectionMs}ms`);
+    }
+  } catch (error) {
+    throw isUltimateError(error)
+      ? error
+      : dbUnavailable('x db diagnostics could not open a connection', error);
+  }
+  const deadline = commandDeadline(DIAGNOSTICS_DEADLINE_MS, schedule);
+  const section = async <Row>(
+    statement: string,
+    toRow: (raw: Readonly<Record<string, unknown>>) => Row,
+    fixFor?: (code: string, reason: string) => string | undefined,
+  ): Promise<DiagnosticSection<Row>> => {
+    if (deadline.passed()) {
+      const reason = `not sent: x db diagnostics passed its ${DIAGNOSTICS_DEADLINE_MS}ms deadline first`;
+      return { available: false, code: TIMED_OUT, reason, fix: GENERIC_FIX };
+    }
+    try {
+      const answer = await within(
+        readOnlyQuery<Readonly<Record<string, unknown>>>(statement, { ...read, maxRows: limit }),
+        sectionMs,
+        schedule,
+      );
+      if (answer === EXPIRED) {
+        // The embedded database cannot interrupt the statement, so it may still be running.
+        const reason = `no answer within ${sectionMs}ms; the client stopped waiting`;
+        return { available: false, code: TIMED_OUT, reason, fix: GENERIC_FIX };
+      }
+      return { available: true, rows: answer.rows.map(toRow) };
+    } catch (error) {
+      const code = isUltimateError(error) ? error.code : 'X_DB_STATEMENT_FAILED';
+      const reason = scrubCredentials(
+        isUltimateError(error) ? error.cause : renderThrowable(error),
+      );
+      const own = isUltimateError(error) ? error.fix : undefined;
+      const fix = fixFor?.(code, reason) ?? own ?? GENERIC_FIX;
+      return { available: false, code, reason, fix: scrubCredentials(fix) };
+    }
+  };
+  try {
+    return await readSections(section);
+  } finally {
+    deadline.release();
+  }
+}
+
+type Section = <Row>(
+  statement: string,
+  toRow: (raw: Readonly<Record<string, unknown>>) => Row,
+  fixFor?: (code: string, reason: string) => string | undefined,
+) => Promise<DiagnosticSection<Row>>;
+
+/** The seven, in order, each through `section`. */
+async function readSections(section: Section): Promise<DbDiagnostics> {
+  return {
+    blockers: await section(BLOCKERS_SQL, (raw) => blockerRow(raw, redactQueryText)),
+    activity: await section(ACTIVITY_SQL, (raw) => activityRow(raw, redactQueryText)),
+    // `42P01` (not installed) and `55000` (installed, not preloaded) both mean the extension is
+    // not answering — its own fix, never `X_DB_SCHEMA_STALE`'s `x db gen`.
+    slowQueries: await section(
+      SLOW_QUERIES_SQL,
+      (raw) => slowQueryRow(raw, redactQueryText),
+      (code, reason) =>
+        code === 'X_DB_SCHEMA_STALE' || reason.includes('pg_stat_statements')
+          ? SLOW_QUERIES_FIX
+          : undefined,
+    ),
+    unusedIndexes: await section(UNUSED_INDEXES_SQL, unusedIndexRow),
+    invalidIndexes: await section(INVALID_INDEXES_SQL, invalidIndexRow),
+    notValidConstraints: await section(NOT_VALID_CONSTRAINTS_SQL, notValidConstraintRow),
+    deadTuples: await section(DEAD_TUPLES_SQL, deadTupleRow),
+  };
+}

package/src/destructive.ts

@@ -3,8 +3,8 @@
 // an *undeclared* drop is not. Only `up` is ever asked: reversing `create table` is `drop table`,
 // so a rail reading `down` would mark every migration ever generated, and a mark on all is none.
 
+import { hasMarkerLine } from './marker-line';
 import { stripSqlNoise } from './sql-noise';
-import { noiseAt } from './sql-scan';
 import { statementExcerpt } from './statement-excerpt';
 import { statementsOf } from './statement-split';
 
@@ -18,40 +18,12 @@ export const DESTRUCTIVE_MARKER = '-- destructive: true';
  */
 const MARKER_COMMENT = /^--[ \t]*destructive:[ \t]*true[ \t]*\r?\n?$/i;
 
-/** Whether only spaces and tabs separate `index` from the start of its line. */
-function startsLine(sql: string, index: number): boolean {
-  for (let at = index - 1; at >= 0; at -= 1) {
-    const char = sql[at];
-    if (char === '\n') return true;
-    if (char !== ' ' && char !== '\t') return false;
-  }
-  return true;
-}
-
 /**
- * Declared only where a reader would see it: a top-level `--` line of its own.
- *
+ * Declared only where a reader would see it: a top-level `--` line of its own (`marker-line.ts`).
  * A regex over the raw file matched the marker inside `/* … *\/` and inside a dollar-quoted body,
- * where it declares nothing and no reviewer reading the diff would call it a declaration — yet it
- * bought the file past `x verify`. Scanning is what tells a comment from a comment about a
- * comment; the marker is a lexical fact, not a substring.
+ * where it declares nothing — yet it bought the file past `x verify`.
  */
-export function hasDestructiveMarker(sql: string): boolean {
-  let index = 0;
-  while (index < sql.length) {
-    const noise = noiseAt(sql, index);
-    if (noise === null) {
-      index += 1;
-      continue;
-    }
-    const text = sql.slice(index, noise.end);
-    if (noise.kind === 'line-comment' && startsLine(sql, index) && MARKER_COMMENT.test(text)) {
-      return true;
-    }
-    index = noise.end;
-  }
-  return false;
-}
+export const hasDestructiveMarker = (sql: string): boolean => hasMarkerLine(sql, MARKER_COMMENT);
 
 export type DestructiveKind = 'drop-table' | 'drop-column' | 'retype-column' | 'truncate';
 
@@ -69,6 +41,20 @@ export interface DestructiveStatement {
   readonly statement: string;
 }
 
+/**
+ * Inside an `alter table`, a bare `drop <name>` is a column: every sub-clause that drops something
+ * the database can rebuild names itself, and all of them are listed here. One list, two readers:
+ * this file's regex and `rolling.ts`'s token walk.
+ */
+export const REBUILDABLE_DROP_CLAUSES: readonly string[] = [
+  'constraint',
+  'default',
+  'not',
+  'identity',
+  'expression',
+  'generated',
+];
+
 /**
  * The closed list. Four kinds, because a rail that tried to enumerate every Postgres foot-gun
  * would be a second SQL parser competing with the server's own — and every one of these is a
@@ -82,11 +68,11 @@ const RULES: readonly (readonly [DestructiveKind, RegExp])[] = [
   // Statement-leading only: `before truncate` in a trigger and `grant/revoke truncate` name the
   // operation to guard or permit it, and the rail read them as the operation itself (#522).
   ['truncate', /^\s*truncate\b/],
-  // Inside an `alter table`, a bare `drop <name>` is a column: every sub-clause that drops
-  // something the database can rebuild names itself, and all of them are listed here.
   [
     'drop-column',
-    /\balter\s+table\b[\s\S]*?\bdrop\s+(?!constraint\b|default\b|not\b|identity\b|expression\b|generated\b)/,
+    new RegExp(
+      `\\balter\\s+table\\b[\\s\\S]*?\\bdrop\\s+(?!${REBUILDABLE_DROP_CLAUSES.map((clause) => `${clause}\\b`).join('|')})`,
+    ),
   ],
   // Not "narrowing". Whether the new type is narrower is knowable only against the old one, and a
   // rewrite that fails on one row fails the whole migration whichever direction it went.

package/src/diagnostics-entry.ts

@@ -0,0 +1,15 @@
+// `@ultimat3/db/diagnostics`: `dbDiagnostics()` and its row types. Its own entry because one caller
+// runs it — `x db diagnostics` — while `@ultimat3/db` is imported by every role of every app: on the
+// barrel these five modules were evaluated by every web, worker and migrate pod to serve nothing.
+
+export type { DbDiagnostics, DbDiagnosticsOptions, DiagnosticSection } from './db-diagnostics';
+export { DIAGNOSTICS_LIMIT, DIAGNOSTICS_TIMEOUT_MS, dbDiagnostics } from './db-diagnostics';
+export type {
+  ActivityRow,
+  BlockerRow,
+  DeadTupleRow,
+  InvalidIndexRow,
+  NotValidConstraintRow,
+  SlowQueryRow,
+  UnusedIndexRow,
+} from './db-diagnostics-rows';

package/src/drift-errors.ts

@@ -9,6 +9,13 @@
 import { DbError } from './errors';
 import { shellInertIdentifier } from './sql';
 
+/**
+ * What a `x db gen` fix owes after its `#`. It diffs entities against the newest snapshot, so a column
+ * only a migration holds is an empty diff: exit 0, the finding still there. Both ways out are named.
+ */
+export const undeclaredColumnNext = (column: string): string =>
+  `declare ${column} on its entity first, or this writes nothing; no entity should hold it: restore the edited migration, then x db reset`;
+
 /**
  * The contract's pinned wording, and the ONE definition of it: `@ultimat3/entity` carried a second
  * `dbDrift()` held in step by a comment and a test, deleted `As of 2026-10-02`. Drift is this
@@ -28,9 +35,7 @@ export const dbDrift = (tableName: string, columnName: string): DbError =>
     cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
     fix:
       shellInertIdentifier(columnName) === null
-        ? 'x db gen "add the column named in this error"   # its name carries a backtick, a ' +
-          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
-          'this command'
-        : `x db gen "add ${columnName}"`,
+        ? `x db gen "add the column named in this error"   # its name carries shell syntax, so it is in the cause and not in this command; ${undeclaredColumnNext('it')}`
+        : `x db gen "add ${columnName}"   # ${undeclaredColumnNext(columnName)}`,
     meta: { table: tableName, column: columnName },
   });