@ultimat3/db 29.4.0 → 30.1.0

package/src/drift-row-security.ts

@@ -0,0 +1,88 @@
+// Single responsibility: `X_DB_ROW_SECURITY_DRIFT` — a tenant table and `database.rowSecurity`
+// disagreeing about its policy, read two ways. Against the migrations (no database: the gate's
+// `drift` step) and against the live catalog (`checkDrift`, after `x db migrate`).
+
+import type { DriftDifference } from './drift-findings';
+import type { EntityDescriptionLike } from './entity-shape';
+import { DbError } from './errors';
+import { type RowSecurityOption, rowSecurityInput } from './generate-row-security';
+import type { SchemaDescription, TableDescription } from './introspect';
+import { ROW_SECURITY_POLICY } from './row-security';
+import { rowSecurityAfter } from './row-security-plan';
+import { shellInertIdentifier } from './sql';
+
+export const ROW_SECURITY_DRIFT_CODE = 'X_DB_ROW_SECURITY_DRIFT';
+
+/** `missing`: the flag wants a policy nothing put there. `stray`: one is there the flag does not want. */
+export interface RowSecurityDifference {
+  readonly table: string;
+  readonly direction: 'missing' | 'stray';
+}
+
+/**
+ * The flag and the tenant columns against what the newest snapshot recorded — the same input
+ * `x db gen` plans from, so the gate never expects a policy the generator would not write.
+ */
+export function rowSecurityDifferences(
+  entities: readonly EntityDescriptionLike[],
+  recorded: SchemaDescription,
+  option: RowSecurityOption,
+): readonly RowSecurityDifference[] {
+  const input = rowSecurityInput(entities, recorded, option);
+  const wanted = rowSecurityAfter(input);
+  return [
+    ...[...wanted]
+      .filter((table) => !input.recorded.has(table))
+      .map((table) => ({ table, direction: 'missing' as const })),
+    ...[...input.recorded]
+      .filter((table) => !wanted.has(table))
+      .map((table) => ({ table, direction: 'stray' as const })),
+  ].sort((a, b) => (a.table < b.table ? -1 : 1));
+}
+
+/** The migrations' reading as an error. The repair is the generation the flag is waiting on. */
+export const rowSecurityDrift = (difference: RowSecurityDifference): DbError =>
+  new DbError({
+    code: ROW_SECURITY_DRIFT_CODE,
+    cause:
+      difference.direction === 'missing'
+        ? `database.rowSecurity is on and no migration gave tenant table "${difference.table}" its policy: a raw sql read of it still sees every tenant's rows`
+        : `database.rowSecurity is off and a migration left tenant table "${difference.table}" its policy: every read without a tenant set sees no rows`,
+    fix: 'x db gen "row security"',
+    meta: { table: difference.table, direction: difference.direction },
+  });
+
+/** Where the statements are, as a command that prints them: the ledger already holds the migration. */
+const statementsOf = (table: string): string => {
+  const name = shellInertIdentifier(table);
+  const pattern = name === null ? ROW_SECURITY_POLICY : `on ${name}`;
+  return `grep -n '${pattern}' packages/db/migrations/*.sql`;
+};
+
+/**
+ * The catalog's reading, judged only where both halves were asked (`compareAppendOnly`'s rule):
+ * a snapshot that predates the field, or a description nobody introspected, says nothing.
+ * `policyNames` holds only an enabled AND forced table's policies, so a disabled or unforced
+ * table reads as missing — an owner or nobody would be bound by it.
+ */
+export function compareRowSecurity(
+  live: TableDescription,
+  expected: TableDescription,
+): DriftDifference[] {
+  if (live.policyNames === undefined) return [];
+  const present = live.policyNames.includes(ROW_SECURITY_POLICY);
+  const wanted = expected.rowSecurity === true;
+  if (present === wanted) return [];
+  const table = live.name;
+  return [
+    {
+      kind: wanted ? 'missing-row-security' : 'unexpected-row-security',
+      table,
+      column: null,
+      cause: wanted
+        ? `table "${table}" should carry the forced tenant policy ${ROW_SECURITY_POLICY} and does not, or its row security is disabled or not forced: raw sql sees every tenant's rows`
+        : `table "${table}" carries the tenant policy ${ROW_SECURITY_POLICY} no migration recorded`,
+      fix: `${statementsOf(table)}   # run the row-security statements it prints against this database with psql "$DATABASE_URL", then x db migrate, which re-checks`,
+    },
+  ];
+}

package/src/drift-triggers.ts

@@ -0,0 +1,54 @@
+// Single responsibility: whether the lifecycle triggers a migration installed — history, its guard,
+// counters — are still enabled on the table, and whether a `retain` table became partitioned. The
+// repository never sees either, so only the catalog can say. `drift-append-only.ts` is the model.
+
+import { byHand, type DriftDifference, pathTo, repair } from './drift-findings';
+import type { TableDescription, TriggerRecord } from './introspect';
+import { shellInertIdentifier } from './sql';
+
+/** The codes `driftError` raises for these kinds, exported so the tests assert the one literal. */
+export const LIFECYCLE_DRIFT_CODE = 'X_LIFECYCLE_TRIGGER_MISSING';
+export const RETAIN_DRIFT_CODE = 'X_ENTITY_RETAIN_INVALID';
+
+/** The fix is the statements `x db gen` wrote, against THIS database: the ledger already holds them. */
+function missingTrigger(live: TableDescription, trigger: TriggerRecord): DriftDifference {
+  const path = pathTo(live.schema);
+  return {
+    kind: 'missing-lifecycle-trigger',
+    table: live.name,
+    column: null,
+    cause:
+      `table "${live.name}" was given trigger ${trigger.name} by a migration, and it is missing or ` +
+      'disabled — writes here no longer record history or keep a counter',
+    fix:
+      path === null || shellInertIdentifier(live.name) === null
+        ? byHand(`re-create trigger ${trigger.name} as the newest migration that names it does`)
+        : repair(path, trigger.install.join(' ')),
+  };
+}
+
+function partitionedRetain(live: TableDescription): DriftDifference {
+  return {
+    kind: 'retain-partitioned',
+    table: live.name,
+    column: null,
+    cause:
+      `table "${live.name}" declares retain and the catalog holds it partitioned: a partitioned ` +
+      "table's retention is detaching its old partitions, never a row-by-row sweep",
+    fix: `x db gen "drop retain"   # after removing retain from the entity on ${live.name}; detach old partitions in a task`,
+  };
+}
+
+/** Judged only where both halves were asked, exactly as `compareAppendOnly` reads its pair. */
+export function compareTriggers(
+  live: TableDescription,
+  expected: TableDescription,
+): DriftDifference[] {
+  const out: DriftDifference[] = [];
+  if (expected.retain === true && live.partitioned === true) out.push(partitionedRetain(live));
+  if (live.triggerNames === undefined) return out;
+  for (const trigger of expected.triggers ?? []) {
+    if (!live.triggerNames.includes(trigger.name)) out.push(missingTrigger(live, trigger));
+  }
+  return out;
+}

package/src/drift.ts

@@ -5,22 +5,27 @@
 
 import { baseClient, type DbClient } from './client';
 import { APPEND_ONLY_DRIFT_CODE, compareAppendOnly } from './drift-append-only';
-import type { DriftDifference } from './drift-findings';
+import type { DriftDifference, DriftKind } from './drift-findings';
 import {
   changedColumn,
   changedForeignKey,
-  changedIndex,
   changedPrimaryKey,
   missingCheck,
-  missingColumn,
-  missingForeignKey,
-  missingIndex,
-  missingTable,
+  notValidConstraint,
   unexpectedColumn,
   unexpectedTable,
   unknownSchema,
 } from './drift-findings';
-import { DbError } from './errors';
+import {
+  changedIndex,
+  missingColumn,
+  missingForeignKey,
+  missingIndex,
+  missingTable,
+} from './drift-missing';
+import { compareRowSecurity, ROW_SECURITY_DRIFT_CODE } from './drift-row-security';
+import { compareTriggers, LIFECYCLE_DRIFT_CODE, RETAIN_DRIFT_CODE } from './drift-triggers';
+import { DbError, type DbErrorCode } from './errors';
 import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
 import {
@@ -76,7 +81,7 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
   for (const index of expected.indexes) {
     const counterpart = present.get(index.name);
     if (counterpart === undefined) {
-      differences.push(missingIndex(live.name, index.name));
+      differences.push(missingIndex(live.schema, live.name, index));
       continue;
     }
     // The method first, and before the column list: a GIN index and a btree over the same column
@@ -86,27 +91,47 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
     // catalog reports as `btree` agree instead of reporting drift on a correct database.
     if (indexMethodOf(counterpart) !== indexMethodOf(index)) {
       differences.push(
-        changedIndex(live.name, index.name, `is a ${indexMethodOf(counterpart)} index`),
+        changedIndex(
+          live.schema,
+          live.name,
+          index,
+          counterpart,
+          `is a ${indexMethodOf(counterpart)} index`,
+        ),
       );
       continue;
     }
     if (counterpart.columns.join(',') !== index.columns.join(',')) {
       differences.push(
-        changedIndex(live.name, index.name, `covers (${counterpart.columns.join(', ')})`),
+        changedIndex(
+          live.schema,
+          live.name,
+          index,
+          counterpart,
+          `covers (${counterpart.columns.join(', ')})`,
+        ),
       );
       continue;
     }
     if (counterpart.unique !== index.unique) {
       differences.push(
-        changedIndex(live.name, index.name, counterpart.unique ? 'is unique' : 'is not unique'),
+        changedIndex(
+          live.schema,
+          live.name,
+          index,
+          counterpart,
+          counterpart.unique ? 'is unique' : 'is not unique',
+        ),
       );
       continue;
     }
     if ((counterpart.order ?? 'asc') !== (index.order ?? 'asc')) {
       differences.push(
         changedIndex(
+          live.schema,
           live.name,
-          index.name,
+          index,
+          counterpart,
           counterpart.order === 'desc' ? 'is descending' : 'is ascending',
         ),
       );
@@ -115,8 +140,10 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
     if ((counterpart.where === null) !== (index.where === null)) {
       differences.push(
         changedIndex(
+          live.schema,
           live.name,
-          index.name,
+          index,
+          counterpart,
           counterpart.where === null ? 'covers every row' : 'is partial',
         ),
       );
@@ -149,7 +176,7 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
   for (const key of expected.foreignKeys) {
     const counterpart = present.get(foreignKeyTarget(key));
     if (counterpart === undefined) {
-      differences.push(missingForeignKey(live.name, key));
+      differences.push(missingForeignKey(live.schema, live.name, key));
       continue;
     }
     if (onDeleteRule(counterpart.onDelete) !== onDeleteRule(key.onDelete)) {
@@ -186,6 +213,25 @@ function compareChecks(live: TableDescription, expected: TableDescription): Drif
     .map((check) => missingCheck(live.schema, live.name, check));
 }
 
+/**
+ * A declared constraint the catalog holds but never validated. Only the declared side, as everywhere
+ * here: a hand-written `NOT VALID` no snapshot records is the app's decision. Foreign keys are read
+ * by where they point, the identity `compareForeignKeys` uses, so a name the catalog holds and the
+ * snapshot does not still counts.
+ */
+function compareValidated(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  const unvalidated = new Set(live.notValidNames ?? []);
+  if (unvalidated.size === 0) return [];
+  const declared = new Set((expected.checks ?? []).map((check) => check.name));
+  const pointed = new Set(expected.foreignKeys.map(foreignKeyTarget));
+  for (const key of live.foreignKeys) {
+    if (pointed.has(foreignKeyTarget(key))) declared.add(key.name);
+  }
+  return [...unvalidated]
+    .filter((name) => declared.has(name))
+    .map((name) => notValidConstraint(live.schema, live.name, name));
+}
+
 /**
  * The two key lists, compared in ORDER. The comment that used to stand here said a key on one side
  * only "is a difference the key comparison owns" — and no key comparison existed, so a table
@@ -213,7 +259,7 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
   for (const column of expected.columns) {
     const counterpart = liveColumns.get(column.name);
     if (counterpart === undefined) {
-      differences.push(missingColumn(live.name, column.name));
+      differences.push(missingColumn(live.schema, live.name, column));
       continue;
     }
     // Nullability, not the type: the catalog and a snapshot spell types differently often enough
@@ -228,12 +274,23 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
   differences.push(...compareIndexes(live, expected));
   differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
+  differences.push(...compareValidated(live, expected));
   differences.push(...compareAppendOnly(live, expected));
+  differences.push(...compareRowSecurity(live, expected));
+  differences.push(...compareTriggers(live, expected));
   return differences;
 }
 
-/** Pure and total: the same inputs always produce the same ordered report. */
-export function diffSchema(live: SchemaDescription, expected: SchemaDescription): DriftReport {
+/**
+ * Pure and total: the same inputs always produce the same ordered report. `schema` is where the
+ * live side was read — a missing table has no live description to say so, and its repair has to
+ * create it there. Default `public`, `introspectSchema()`'s own.
+ */
+export function diffSchema(
+  live: SchemaDescription,
+  expected: SchemaDescription,
+  schema = 'public',
+): DriftReport {
   const differences: DriftDifference[] = [];
   for (const table of live.tables) {
     const counterpart = findTable(expected, table.name);
@@ -241,7 +298,9 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
     else differences.push(...compareTable(table, counterpart));
   }
   for (const table of expected.tables) {
-    if (findTable(live, table.name) === undefined) differences.push(missingTable(table.name));
+    if (findTable(live, table.name) === undefined) {
+      differences.push(missingTable(schema, table.name, table.columns, table.primaryKey));
+    }
   }
   differences.sort((a, b) => {
     if (a.table !== b.table) return a.table < b.table ? -1 : 1;
@@ -251,10 +310,18 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
   return { ok: differences.length === 0, differences };
 }
 
+/** The kinds that carry their own code — the guarantee each names is the entity's, not a column's. */
+const OWN_CODE: ReadonlyMap<DriftKind, DbErrorCode> = new Map<DriftKind, DbErrorCode>([
+  ['missing-append-only-trigger', APPEND_ONLY_DRIFT_CODE],
+  ['missing-row-security', ROW_SECURITY_DRIFT_CODE],
+  ['unexpected-row-security', ROW_SECURITY_DRIFT_CODE],
+  ['missing-lifecycle-trigger', LIFECYCLE_DRIFT_CODE],
+  ['retain-partitioned', RETAIN_DRIFT_CODE],
+]);
+
 export function driftError(difference: DriftDifference): DbError {
   return new DbError({
-    // One kind carries its own code — the guarantee it names is the entity's, not a column's.
-    code: difference.kind === 'missing-append-only-trigger' ? APPEND_ONLY_DRIFT_CODE : 'X_DB_DRIFT',
+    code: OWN_CODE.get(difference.kind) ?? 'X_DB_DRIFT',
     cause: difference.cause,
     fix: difference.fix,
     meta: { kind: difference.kind, table: difference.table, column: difference.column },
@@ -360,5 +427,5 @@ export async function checkDrift(options: DriftOptions): Promise<DriftReport> {
     client,
     ...(options.schema === undefined ? {} : { schema: options.schema }),
   });
-  return diffSchema(appTables(live), expected);
+  return diffSchema(appTables(live), expected, options.schema);
 }

package/src/entity-shape.ts

@@ -45,6 +45,16 @@ export interface ColumnDescriptionLike {
    * is REPORTED as unrendered rather than dropped (`unrendered.ts`).
    */
   readonly default?: ColumnDefaultLike | undefined;
+  /**
+   * Both ends of this `references()` are tenant-scoped, so the key is composite: `(column, this) ->
+   * target (targetColumn, its key)`. Absent or `null` is the plain key every older description
+   * declares. `@ultimat3/entity` decides it (`describeReferences`), and only the two physical names
+   * cross, because the rest of the key is already on this column.
+   */
+  readonly sameTenant?:
+    | { readonly column: string; readonly targetColumn: string }
+    | null
+    | undefined;
 }
 
 /**
@@ -125,4 +135,61 @@ export interface EntityDescriptionLike {
    * Optional for the reason `invariants` is, and absent reads as "rows may change".
    */
   readonly appendOnly?: boolean | undefined;
+  /**
+   * `entity({ retired: ['legacy'] })`: physical columns old pods may still read and this release
+   * does not (`retired.ts`). Absent is none, for the reason `invariants` is optional.
+   */
+  readonly retired?: readonly string[] | undefined;
+  /**
+   * `entity(name, { view: { sql } })`: a relation Postgres derives, emitted by `generate-view.ts`
+   * and handed to no table arm. Absent is a table, for the reason `invariants` is optional.
+   */
+  readonly view?: { readonly sql: string; readonly materialized?: true | undefined } | undefined;
+  /**
+   * `entity({ history: true })`: every row change is recorded into `history.table` by a trigger
+   * (`generate-history.ts`). Absent is no history, for the reason `invariants` is optional.
+   */
+  readonly history?: HistoryDescriptionLike | undefined;
+  /**
+   * `references(…, { countedIn })` on a child key: counters the database keeps on this table
+   * (`generate-counter.ts`). Absent is none.
+   */
+  readonly counts?: readonly CounterDescriptionLike[] | undefined;
+  /** `entity({ retain })`: rows older than the window are swept by `purge()`. Absent is kept. */
+  readonly retain?: RetainDescriptionLike | undefined;
+}
+
+/** Where a table's row images go, and what its trigger needs to write one. Physical names. */
+export interface HistoryDescriptionLike {
+  /** The history table: `<table>_history`, an entity of its own. */
+  readonly table: string;
+  /** The parent's single primary-key column, recorded as `row_id`. */
+  readonly key: string;
+  /** The parent's tenant column, copied onto every history row, or `null`. */
+  readonly tenant: string | null;
+  /** Columns whose change alone records nothing: the counters the database keeps. */
+  readonly ignore: readonly string[];
+  /** `int8`/`numeric` columns the image stores as their digits, never a JSON number. */
+  readonly text?: readonly string[] | undefined;
+  /** `timestamptz` columns the image stores as a UTC ISO string, whatever the session zone. */
+  readonly instants?: readonly string[] | undefined;
+}
+
+/** One counter, physical names: `<this table>.<column>` counts `<table>` rows by `<references>`. */
+export interface CounterDescriptionLike {
+  readonly column: string;
+  /** The parent's key column the child's foreign key points at. */
+  readonly key: string;
+  /** The child table the trigger sits on. */
+  readonly table: string;
+  /** The child's foreign-key column. */
+  readonly references: string;
+  /** The child's soft-delete column: a stamped row is not counted. `null` when it has none. */
+  readonly softDelete: string | null;
+}
+
+/** `retain: { after, on }`, with `on` physical. */
+export interface RetainDescriptionLike {
+  readonly after: string;
+  readonly on: string;
 }

package/src/errors.ts

@@ -11,7 +11,8 @@ import {
   stringField,
   UltimateError,
 } from '@ultimat3/core';
-import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
+import { IDLE_IN_TRANSACTION_FIX, poolerOptionsRefusedFix } from './pooler-fix';
+import { type DbSqlStateCode, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';
 
 /**
  * Codes this package declares and owns. `X_DB_DRIFT` is db's: it is a statement about migrations
@@ -44,6 +45,19 @@ export const DB_OWNED_ERROR_CODES = [
   'X_APPEND_ONLY_TRIGGER_MISSING',
   'X_MIGRATION_APPEND_ONLY_BACKFILL',
   'X_MIGRATION_CONCURRENT_IN_TRANSACTION',
+  'X_DB_TRANSACTION_CLOSED',
+  'X_MIGRATION_ROLLING_UNSAFE',
+  'X_DB_POOLER_OPTIONS_REFUSED',
+  'X_DB_POOLER_SESSION_REQUIRED',
+  'X_DB_STATEMENT_BOUND_LOST',
+  'X_DB_STATEMENT_BOUND_INVALID',
+  'X_MIGRATION_CONCURRENT_PARTITIONED',
+  'X_DB_ROW_SECURITY_BYPASSED',
+  'X_DB_ROW_SECURITY_DRIFT',
+  'X_KEYSET_NULL_KEY',
+  'X_MIGRATION_ROLLBACK_DESTRUCTIVE',
+  'X_ENTITY_RETAIN_INVALID',
+  'X_LIFECYCLE_TRIGGER_MISSING',
 ] as const;
 
 /**
@@ -97,6 +111,26 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
     'a NOT NULL column added to an append-only table needs a default',
   X_MIGRATION_CONCURRENT_IN_TRANSACTION:
     'a concurrent index statement is in a migration that runs inside a transaction',
+  X_DB_TRANSACTION_CLOSED: 'statement on a finished transaction',
+  X_MIGRATION_ROLLING_UNSAFE:
+    'this drop or rename would break the pods still running the old release',
+  X_DB_POOLER_OPTIONS_REFUSED:
+    'the connection pooler refused the libpq options a pool connects with',
+  X_DB_POOLER_SESSION_REQUIRED:
+    'this role needs one backend per session, and a transaction pooler gives it none',
+  X_DB_STATEMENT_BOUND_LOST: "the session's statement bound is not the role's",
+  X_DB_STATEMENT_BOUND_INVALID:
+    'a statement bound is not a whole positive number of ms under the role bound',
+  X_MIGRATION_CONCURRENT_PARTITIONED: 'a concurrent index build names a partitioned table',
+  X_DB_ROW_SECURITY_BYPASSED: 'row security is on and the serving role is exempt from it',
+  X_DB_ROW_SECURITY_DRIFT: 'a tenant table and database.rowSecurity disagree about its policy',
+  X_KEYSET_NULL_KEY: 'a keyset page holds a null in one of its sort keys',
+  X_MIGRATION_ROLLBACK_DESTRUCTIVE:
+    'a rollback would serve an older build over a destructive migration',
+  X_ENTITY_RETAIN_INVALID:
+    'entity({ retain }) has no window, sits beside appendOnly, or is on a partitioned table',
+  X_LIFECYCLE_TRIGGER_MISSING:
+    'a history or counter trigger the migrations created is missing from the database',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails
@@ -200,6 +234,18 @@ export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
     sourceError,
   });
 
+/**
+ * No answer past the role's bound plus the grace (`pool-sweep.ts`), so the server's own bound had to
+ * have answered and the path is dead. The same uncertainty as a connection closed mid-statement,
+ * which is why the cause says it. `X_DB_UNAVAILABLE` is deliberately left out of `DB_ERROR_RETRY`
+ * (unclassified, not terminal), so a job worker RE-RUNS the attempt: an autocommit write that landed
+ * runs again. At least once, as every job is: the write must be idempotent or inside a transaction.
+ */
+export const statementUnanswered = (excerpt: string, boundMs: number): DbError =>
+  dbUnavailable(
+    `no answer within ${boundMs}ms to: ${excerpt} — past the statement bound, so the path is dead and this pool is replaced; if this was an autocommit write it may have landed`,
+  );
+
 /**
  * One `fix:` per classified SQLSTATE, written once. Every one names a command that exists or an
  * edit the reader can make — a `23505` telling an operator the database is unreachable is the
@@ -218,14 +264,14 @@ const SQLSTATE_FIXES = Object.freeze<Record<DbSqlStateCode, string>>({
     'or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is',
   X_DB_FOREIGN_KEY_VIOLATION:
     'insert the row {constraint} points at first, in the same withTransaction(...) — ' +
-    'or drop the write, because the parent it names is gone',
+    "or drop the write, because the parent it names is gone or is not this tenant's",
   X_DB_SERIALIZATION_FAILURE:
     'withTransaction(fn, { retry: 3 })   # fn re-runs from the top, so it must be idempotent',
   X_DB_STATEMENT_TIMEOUT:
     'add the index this statement needs to the entity (indexes: [...]), then: x db gen "add index"',
   X_DB_LOCK_TIMEOUT:
-    `psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'"` +
-    '   # end the blocker, then re-run the statement',
+    "x db diagnostics --json | jq '.data.blockers.rows[] | {pid, blockedBy, blockerState}'" +
+    '   # end the blockedBy session or wait for it, then re-run the statement',
   X_DB_POOL_EXHAUSTED:
     'set DATABASE_POOL_MAX below max_connections / replicas (per-role default: POOL_PROFILES), ' +
     'or cut the replica count',
@@ -256,6 +302,24 @@ export const driverError = (statement: string, sourceError: unknown): DbError =>
   // `X_DB_UNAVAILABLE` said "set DATABASE_URL" to a developer whose database was fine.
   const code = sqlStateCode(sourceError) ?? 'X_DB_STATEMENT_FAILED';
   const constraint = stringField(sourceError, 'constraint');
+  // `08P01` is the protocol's general complaint, so the pooler's own sentence is what decides, and
+  // this one reached no statement: it is the connection every statement of the role would use.
+  if (
+    state === SQLSTATE.protocolViolation &&
+    renderThrowable(sourceError).includes('unsupported startup parameter')
+  ) {
+    // The identifier characters only: the server's text runs on past the name.
+    const parameter = /unsupported startup parameter(?: in options)?: ([A-Za-z0-9_.]+)/.exec(
+      stringField(sourceError, 'message') ?? renderThrowable(sourceError),
+    )?.[1];
+    return new DbError({
+      code: 'X_DB_POOLER_OPTIONS_REFUSED',
+      cause: `[SQLSTATE ${state}] ${renderThrowable(sourceError)} — statement: ${statement}`,
+      fix: poolerOptionsRefusedFix(parameter),
+      meta: { sqlState: state },
+      sourceError,
+    });
+  }
   return new DbError({
     code,
     // The server's SQLSTATE and message FIRST, the statement after: a cause is rendered on one
@@ -268,9 +332,11 @@ export const driverError = (statement: string, sourceError: unknown): DbError =>
     // ours — `$` is legal in a Postgres identifier, so `posts_$&_key` would splice the matched
     // `{constraint}` back into the fix line an author is meant to paste.
     fix:
-      code === 'X_DB_STATEMENT_FAILED'
-        ? `psql "$DATABASE_URL" -c "<the statement in cause>"   # SQLSTATE ${state} is the server's verdict on it: fix the SQL or the data it names, not the connection`
-        : SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
+      state === SQLSTATE.idleInTransactionTimeout
+        ? IDLE_IN_TRANSACTION_FIX
+        : code === 'X_DB_STATEMENT_FAILED'
+          ? `psql "$DATABASE_URL" -c "<the statement in cause>"   # SQLSTATE ${state} is the server's verdict on it: fix the SQL or the data it names, not the connection`
+          : SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
     meta: {
       sqlState: state,
       ...(constraint === undefined ? {} : { constraint }),
@@ -320,9 +386,11 @@ export const poolAcquireTimeout = (waitedMs: number, max: number): DbError =>
 export const poolMaxInvalid = (received: string): DbError =>
   new DbError({
     code: 'X_ENV_MISSING',
-    cause: `DATABASE_POOL_MAX is ${JSON.stringify(received)}, which is not a positive integer`,
+    // `describeValue`, never the value, in the cause AND meta: an operator who pasted a connection
+    // string here would read its password in the boot log and every `--json` payload.
+    cause: `DATABASE_POOL_MAX is ${describeValue(received)}, which is not a positive integer`,
     fix: 'DATABASE_POOL_MAX=20   # a whole number of connections per process, or unset it',
-    meta: { received },
+    meta: { received: describeValue(received) },
   });
 
 /**

package/src/expected-loop.ts

@@ -1,7 +1,7 @@
-// Single responsibility: the one way to declare that a loop of statements is deliberate, so a
-// statement-level diagnostic reports the loops nobody argued for and stays quiet about the rest.
-// A scope with a written reason — never a comment pragma and never a config list of exempt call
-// sites (axiom 1), because both put the argument somewhere other than the loop it defends.
+// Single responsibility: the one way to declare a loop of statements deliberate, or a statement a
+// whole-table read, so a diagnostic reports only what nobody argued for. A scope with a written
+// reason — never a comment pragma nor a config list of exempt call sites (axiom 1): both put the
+// argument somewhere other than the statement it defends.
 
 // The reason has to outlive every `await` inside the scope and a module-scope variable would be
 // shared by two concurrent loops, so it needs an async context — opened through core's one lazy
@@ -52,3 +52,33 @@ export function expectedQueryLoop<T>(reason: string, fn: () => T): T {
 export function expectedQueryLoopReason(): string | undefined {
   return storage.get();
 }
+
+const scans = asyncContext<string>('the expected-seq-scan reason');
+
+/**
+ * Run `fn` with every statement it issues marked as one that must read its table whole, carrying
+ * `reason`. The plan sweep `x exercise` runs reads it off each statement it saw, and lists the
+ * statement as exempt with the reason instead of `X_QUERY_UNINDEXED` — for a hand-written report
+ * over every row, never for a lookup that lacks its index. A table that is small by nature says so
+ * once, on the entity: `entity('plans', { scan: '<why>' })`. Same shape as `expectedQueryLoop`:
+ * required, non-blank, innermost wins, and a verdict suppressed — the statement still runs.
+ *
+ * ```ts
+ * await expectedSeqScan('the nightly digest reads every subscription once', () =>
+ *   db().query(sql`select id, email from subscriptions where active`),
+ * );
+ * ```
+ */
+export function expectedSeqScan<T>(reason: string, fn: () => T): T {
+  assert(
+    reason.trim() !== '',
+    'expectedSeqScan() was given a blank reason, so the scan it exempts carries no argument',
+    "pass why the statement must read the whole table: expectedSeqScan('the nightly digest reads every row once', fn)",
+  );
+  return scans.run(reason, fn);
+}
+
+/** The innermost `expectedSeqScan` reason in force, or `undefined` outside every scope. */
+export function expectedSeqScanReason(): string | undefined {
+  return scans.get();
+}