@ultimat3/db 29.4.0 → 30.0.0

package/src/concurrent-plan.ts

@@ -1,9 +1,14 @@
-// Single responsibility: the index work `x db gen` moves OUT of the migration's transaction into a
-// step of its own — every `concurrently: true` build and every index REMOVAL, whose concurrent
-// forms queue no read and no write, and which Postgres runs only outside a transaction block.
-// `index-plan.ts` decides which; this file writes the statements and the intermediate snapshot.
+// 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,
@@ -12,7 +17,7 @@ import {
   indexShape,
   mayBeConstraintBacked,
 } from './index-ddl';
-import type { IndexDescription, SchemaDescription } from './introspect';
+import type { ForeignKeyDescription, IndexDescription, SchemaDescription } from './introspect';
 import { identifier } from './sql';
 
 /**
@@ -23,18 +28,42 @@ 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;
 }
 
 /**
- * The non-transactional step's statements, in two phases, and what each changes for the snapshot.
- * `up`/`down` EXPAND (every build), `contract`/`contractDown` CONTRACT (every removal): the step
- * runs all of the first before any of the second, so a replacement exists before what it replaces
- * goes — across tables too, since the phases are joined once, at assembly (`stepStatements`).
+ * 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 => ({
@@ -43,19 +72,31 @@ export const emptyConcurrentPlan = (): ConcurrentPlan => ({
   contract: [],
   contractDown: [],
   deferred: [],
+  keys: [],
+  keysDown: [],
+  validate: [],
+  contractKeys: [],
+  contractKeysDown: [],
+  deferredKeys: [],
 });
 
 /**
- * The step's script in apply order — expand, then contract — and its reversal: the removed
- * indexes are restored FIRST, then the new ones dropped, so the reversal has no gap either.
+ * 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.contract],
-    down: [...plan.down, ...plan.contractDown].reverse(),
+    up: [...plan.up, ...plan.keys, ...plan.validate, ...plan.contractKeys, ...plan.contract],
+    down: [
+      ...plan.down,
+      ...plan.keysDown,
+      ...plan.contractKeysDown,
+      ...plan.contractDown,
+    ].reverse(),
   };
 }
 
@@ -67,7 +108,75 @@ export function buildConcurrently(
 ): void {
   concurrent.up.push(createIndex(table, index, true));
   concurrent.down.push(dropIndexConcurrently(index.name));
-  concurrent.deferred.push({ table, name: 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));
 }
 
 /**
@@ -145,7 +254,7 @@ export function redefineConcurrently(
     createIndex(table, asDeclared(recorded), true),
     dropIndexConcurrently(index.name),
   );
-  concurrent.deferred.push({ table, name: index.name, recorded });
+  concurrent.deferred.push({ table, name: index.name, recorded, builds: builtBy(index) });
 }
 
 /**
@@ -153,23 +262,32 @@ export function redefineConcurrently(
  * 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.
+ * 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);
-      if (mine.length === 0) return table;
+      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;
+}

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`;