@ultimat3/db 29.3.2 → 30.0.0

package/src/pool-listeners.ts

@@ -0,0 +1,143 @@
+// Single responsibility: the LISTEN sessions a `postgresClient` holds beside its pool, and carrying
+// them across a retired pool. `Bun.SQL` re-dials a session whose backend died, but `close()` ends it
+// for good, so a retirement would leave `startQueueWake` reporting live on a session that is gone.
+
+import { backoffDelay, logger, renderThrowable, type Scheduler } from '@ultimat3/core';
+import type { BunSqlDriver } from './bun-sql';
+import { DbError, driverError } from './errors';
+import { assertListenChannel, type DbSubscription, listenUnsupported } from './listen';
+import { unrefSchedule } from './pool-timer';
+
+const REDIAL_BASE_MS = 1_000;
+const REDIAL_MAX_MS = 30_000;
+
+type Session = Awaited<ReturnType<NonNullable<BunSqlDriver['listen']>>>;
+
+export interface PoolListeners {
+  listen(
+    channel: string,
+    onNotify: (payload: string) => void,
+    onListening?: () => void,
+  ): Promise<DbSubscription>;
+  /** The pool behind every session is gone: establish each again on the current one. */
+  redial(): void;
+  /** `close()` ended every session, and the client is done with them. */
+  drop(): void;
+}
+
+interface Held {
+  readonly channel: string;
+  readonly onNotify: (payload: string) => void;
+  readonly onListening: (() => void) | undefined;
+  session: Session | undefined;
+  /** Moved by each redial: a dial the next retirement overtook is nobody's. */
+  dial: number;
+  cancelRetry: () => void;
+  ended: boolean;
+}
+
+export function poolListeners(
+  currentPool: () => Pick<BunSqlDriver, 'listen'>,
+  schedule: Scheduler = unrefSchedule,
+): PoolListeners {
+  const held = new Set<Held>();
+
+  /** Best-effort, the rule `releaseReserved` states: the session may be gone with its pool. */
+  const end = (session: Session): Promise<void> =>
+    session.unlisten().catch((error: unknown) => {
+      logger.debug('db.unlisten_failed', { error: renderThrowable(error) });
+    });
+
+  const dialOn = (entry: Held): Promise<Session> => {
+    const pool = currentPool();
+    if (pool.listen === undefined) throw listenUnsupported('this Bun.SQL');
+    return pool.listen(entry.channel, entry.onNotify, entry.onListening);
+  };
+
+  function redialOne(entry: Held, attempt: number): void {
+    // The session is gone NOW, whether or not a re-dial ever lands: `startQueueWake` un-proves the
+    // wake on this cue, so the loops drop to the poll's ceiling instead of trusting a dead session.
+    // Once per retirement, not per refused attempt: each cue sends a probe.
+    if (attempt === 1) entry.onListening?.();
+    entry.dial += 1;
+    const dial = entry.dial;
+    const overtaken = (): boolean => entry.ended || dial !== entry.dial;
+    entry.cancelRetry();
+    entry.session = undefined;
+    // `async` so a pool that cannot be built (`currentPool` throws) lands in the retry too.
+    void (async () => dialOn(entry))().then(
+      (session) => {
+        if (overtaken()) void end(session);
+        else entry.session = session;
+      },
+      (error: unknown) => {
+        if (overtaken()) return;
+        logger.warn('db.listen.redial_failed', {
+          channel: entry.channel,
+          attempt,
+          error: renderThrowable(error),
+        });
+        // Equal jitter: a fleet that lost its database together must not re-dial it together.
+        const wait = backoffDelay({
+          attempt,
+          base: REDIAL_BASE_MS,
+          max: REDIAL_MAX_MS,
+          jitter: 'equal',
+        });
+        entry.cancelRetry = schedule(() => redialOne(entry, attempt + 1), wait);
+      },
+    );
+  }
+
+  return {
+    async listen(channel, onNotify, onListening) {
+      assertListenChannel(channel);
+      const entry: Held = {
+        channel,
+        onNotify,
+        onListening,
+        session: undefined,
+        dial: 0,
+        cancelRetry: () => undefined,
+        ended: false,
+      };
+      held.add(entry);
+      try {
+        // The driver's own session, never a pin out of the pool: a reserved connection holds the
+        // LISTEN and surfaces no notification, and it would cost the pool a slot for good.
+        const session = await dialOn(entry);
+        if (entry.dial === 0 && !entry.ended) entry.session = session;
+        else void end(session);
+      } catch (error) {
+        // A retirement mid-dial already took this subscription over: its redial is the answer.
+        if (entry.dial === 0) {
+          held.delete(entry);
+          if (error instanceof DbError) throw error;
+          throw driverError(`LISTEN ${channel}`, error);
+        }
+      }
+      let ended: Promise<void> | undefined;
+      return {
+        unlisten: () => {
+          ended ??= (async () => {
+            entry.ended = true;
+            entry.cancelRetry();
+            held.delete(entry);
+            if (entry.session !== undefined) await end(entry.session);
+          })();
+          return ended;
+        },
+      };
+    },
+    redial() {
+      for (const entry of held) redialOne(entry, 1);
+    },
+    drop() {
+      for (const entry of held) {
+        entry.ended = true;
+        entry.cancelRetry();
+      }
+      held.clear();
+    },
+  };
+}

package/src/pool-pins.ts

@@ -0,0 +1,68 @@
+// Single responsibility: the unanswered-statement bound of ONE pinned connection. A pin's statements
+// are swept like any other, against the `statement_timeout` in force on that connection: the role's,
+// until a `set_config('statement_timeout', …)` or `SET [LOCAL] statement_timeout` it answered moves
+// it, and back to the role's at the transaction's end. A miss leaves the pin dead, never reused.
+
+import type { SqlFragment } from './sql';
+
+/** What one pin is bound by now. `boundMs` 0 is no bound, as the server reads it. */
+export interface PinBound {
+  boundMs: number;
+  /** A statement on it went unanswered: nothing more is sent on this connection. */
+  dead: boolean;
+}
+
+export function pinBound(roleBoundMs: number): PinBound {
+  return { boundMs: roleBoundMs, dead: false };
+}
+
+/** The sweep's deadline for the next statement on `pin`; `0` is none to judge. */
+export function pinDeadlineMs(pin: PinBound, extraMs: number): number {
+  return pin.boundMs === 0 ? 0 : pin.boundMs + extraMs;
+}
+
+/** `setLocal`'s text (`local-settings.ts`), the framework's one writer, held by `pool-pins.test.ts`. */
+const SET_CONFIG = 'select set_config($1, $2, true)';
+const SET_TEXT = /^\s*set\s+(?:local\s+|session\s+)?statement_timeout\s*(?:=|to)\s*(.+?)\s*;?\s*$/i;
+const SET_CONFIG_TEXT =
+  /^\s*select\s+set_config\s*\(\s*'statement_timeout'\s*,\s*'([^']*)'\s*,\s*(?:true|false)\s*\)\s*;?\s*$/i;
+const ENDS_TRANSACTION = /^\s*(?:commit|rollback|end|abort)(?:\s+(?:work|transaction))?\s*;?\s*$/i;
+const UNITS: ReadonlyMap<string, number> = new Map([
+  ['us', 0.001],
+  ['ms', 1],
+  ['s', 1_000],
+  ['min', 60_000],
+  ['h', 3_600_000],
+  ['d', 86_400_000],
+]);
+
+/** A `statement_timeout` value in Postgres' own grammar, as ms: a bare number is ms. */
+export function timeoutValueMs(value: unknown): number | undefined {
+  if (typeof value !== 'string' && typeof value !== 'number') return undefined;
+  const match = /^\s*'?\s*(\d+(?:\.\d+)?)\s*([a-z]*)\s*'?\s*$/i.exec(String(value));
+  if (match === null) return undefined;
+  const scale = UNITS.get((match[2] ?? '').toLowerCase() || 'ms');
+  if (scale === undefined) return undefined;
+  return Math.round(Number(match[1]) * scale);
+}
+
+/** The bound `fragment` sets, or `undefined` when it sets none (or one this cannot read). */
+export function boundSetBy(fragment: SqlFragment): number | undefined {
+  if (fragment.text === SET_CONFIG) {
+    return fragment.values[0] === 'statement_timeout'
+      ? timeoutValueMs(fragment.values[1])
+      : undefined;
+  }
+  const text = SET_TEXT.exec(fragment.text) ?? SET_CONFIG_TEXT.exec(fragment.text);
+  return text === null ? undefined : timeoutValueMs(text[1]);
+}
+
+/** After `fragment` ANSWERED on `pin`: a refused statement moved nothing. */
+export function noteAnswered(pin: PinBound, fragment: SqlFragment, roleBoundMs: number): void {
+  if (ENDS_TRANSACTION.test(fragment.text)) {
+    pin.boundMs = roleBoundMs;
+    return;
+  }
+  const set = boundSetBy(fragment);
+  if (set !== undefined) pin.boundMs = set;
+}

package/src/pool-profile.ts

@@ -1,6 +1,6 @@
-// Single responsibility: the six numbers a Postgres pool runs on — the per-role defaults, the one
-// environment override an operator may layer over them, and the screen every resolved profile
-// passes. Split from `client.ts`, which now owns connecting and nothing about sizing.
+// Single responsibility: the seven numbers a Postgres pool runs on — the per-role defaults, the
+// environment an operator may layer over them (a pool size), and the screen
+// every resolved profile passes. Split from `client.ts`, which now owns connecting and nothing about sizing.
 
 import { assert, type Role, resolveRole } from '@ultimat3/core';
 import { poolMaxInvalid } from './errors';
@@ -19,7 +19,8 @@ export interface PoolProfile {
    */
   readonly lockTimeoutMs: number;
   /**
-   * How long `reserve()` may wait for a free connection before `X_DB_POOL_EXHAUSTED`. 0 waits
+   * How long a plain statement or `reserve()` may wait for a free connection before
+   * `X_DB_POOL_EXHAUSTED`. 0 waits
    * forever, which is what a run-once role wants and what a request-serving one must never do:
    * queueing turns exhaustion into a hang, `/readyz`'s `select 1` joins the same queue, the kubelet
    * kills the pod, and the replacement inherits the same saturated database.
@@ -43,6 +44,14 @@ export interface PoolProfile {
    * run-once role cutting off its own session mid-statement is worse than a slow exit.
    */
   readonly drainTimeoutMs: number;
+  /**
+   * How long a transaction may sit idle before the SERVER closes it, `25P03`. 0 disables the bound:
+   * `migrate` and `replicator`, for `statementTimeoutMs`' reason. A handler awaiting a hung call
+   * inside a transaction holds a slot and its row locks past the request's own 504, and nothing
+   * else ends it: `statement_timeout` only times a statement, and an idle transaction runs none.
+   * Longer on `worker` and `scheduler`, whose steps are expected to take their time.
+   */
+  readonly idleInTransactionMs: number;
 }
 
 /** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
@@ -54,6 +63,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     lockTimeoutMs: 0,
     acquireTimeoutMs: 5_000,
     drainTimeoutMs: 5_000,
+    idleInTransactionMs: 30_000,
   },
   sync: {
     max: 10,
@@ -62,6 +72,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     lockTimeoutMs: 0,
     acquireTimeoutMs: 5_000,
     drainTimeoutMs: 5_000,
+    idleInTransactionMs: 30_000,
   },
   worker: {
     max: 8,
@@ -70,6 +81,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     lockTimeoutMs: 0,
     acquireTimeoutMs: 10_000,
     drainTimeoutMs: 15_000,
+    idleInTransactionMs: 120_000,
   },
   scheduler: {
     max: 2,
@@ -78,6 +90,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     lockTimeoutMs: 0,
     acquireTimeoutMs: 10_000,
     drainTimeoutMs: 5_000,
+    idleInTransactionMs: 120_000,
   },
   // `migrate` waits: its pool is `max: 1` and the advisory-lock pin holds it for the whole run, so
   // a deadline here would refuse the migration's own session. The wait that needed bounding is the
@@ -89,6 +102,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     lockTimeoutMs: 3_000,
     acquireTimeoutMs: 0,
     drainTimeoutMs: 0,
+    idleInTransactionMs: 0,
   },
   replicator: {
     max: 4,
@@ -97,6 +111,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     lockTimeoutMs: 0,
     acquireTimeoutMs: 0,
     drainTimeoutMs: 0,
+    idleInTransactionMs: 0,
   },
 });
 
@@ -125,13 +140,13 @@ export function poolMaxFromEnv(
 }
 
 /**
- * The six numbers a pool runs on, screened on the MERGED profile — an override is spread over a
+ * The seven numbers a pool runs on, screened on the MERGED profile — an override is spread over a
  * role default the caller never restated, so the resolved object is the only one that can be
  * judged. Every one of them is a plausible `Number(process.env.…)`, which is `NaN` for an unset
- * variable and not nullish, so `??` and the spread both keep it. None of the six then fails
+ * variable and not nullish, so `??` and the spread both keep it. None of the seven then fails
  * loudly: `idleTimeout: NaN` goes to `Bun.SQL`, `statement_timeout=NaN` goes into the libpq
  * options string for the SERVER to reject on connect, and a timer given `NaN` fires at 1ms in this
- * Bun — so a pool with free connections reports itself exhausted. `0` stays legal for the five
+ * Bun — so a pool with free connections reports itself exhausted. `0` stays legal for the six
  * budgets that document it as "no bound"; `max` is at least one connection, or nothing can run.
  */
 export function assertPoolProfile(profile: PoolProfile): PoolProfile {
@@ -148,5 +163,6 @@ export function assertPoolProfile(profile: PoolProfile): PoolProfile {
   whole('lockTimeoutMs', profile.lockTimeoutMs, 0);
   whole('acquireTimeoutMs', profile.acquireTimeoutMs, 0);
   whole('drainTimeoutMs', profile.drainTimeoutMs, 0);
+  whole('idleInTransactionMs', profile.idleInTransactionMs, 0);
   return profile;
 }

package/src/pool-reserve.ts

@@ -15,10 +15,14 @@ import type { PoolProfile } from './pool-profile';
  * The losing reservation is released, never dropped: the pool hands out a connection whenever one
  * frees, deadline or no deadline, and a pin nobody holds is a connection nobody gets back. That is
  * the whole reason this is not a bare `Promise.race`.
+ *
+ * `leftMs` is what the caller's wait left of the ONE budget, and the timer runs on it; the refusal
+ * still names `acquireTimeoutMs`, the budget the operator configured and the wait it describes.
  */
 export async function reserveWithin(
   pool: Pick<BunSqlDriver, 'reserve'>,
   profile: PoolProfile,
+  leftMs: number = profile.acquireTimeoutMs,
 ): Promise<BunSqlReserved> {
   const budget = profile.acquireTimeoutMs;
   if (budget <= 0) return pool.reserve();
@@ -29,10 +33,13 @@ export async function reserveWithin(
     return await Promise.race([
       pending,
       new Promise<never>((_resolve, reject) => {
-        timer = setTimeout(() => {
-          expired = true;
-          reject(poolAcquireTimeout(budget, profile.max));
-        }, budget);
+        timer = setTimeout(
+          () => {
+            expired = true;
+            reject(poolAcquireTimeout(budget, profile.max));
+          },
+          Math.max(1, leftMs),
+        );
         // The deadline must not be what keeps a finished process alive.
         timer.unref?.();
       }),

package/src/pool-retire.ts

@@ -0,0 +1,22 @@
+// Single responsibility: letting go of a pool that stopped answering. Bun.SQL exposes no one
+// connection to close, and a statement past its bound means a dead path, so its siblings on that path
+// are suspect too: the whole pool goes, in the background, and the next statement builds a new one.
+
+import { logger, renderThrowable } from '@ultimat3/core';
+import type { BunSqlDriver } from './bun-sql';
+
+/**
+ * Measured against a TCP proxy blackholing every connection: `close({ timeout: 1 })` returned at
+ * 1003 ms, the hung statement rejected `ERR_POSTGRES_CONNECTION_CLOSED`, a new pool answered on the
+ * same proxy. **The unit is seconds.** Total: a caller is already holding the error that matters.
+ */
+export function closeRetiredPool(pool: Pick<BunSqlDriver, 'close'>): void {
+  const report = (error: unknown): void => {
+    logger.warn('db.pool.retire_failed', { error: renderThrowable(error) });
+  };
+  try {
+    void pool.close({ timeout: 1 }).then(undefined, report);
+  } catch (error) {
+    report(error);
+  }
+}

package/src/pool-sweep.ts

@@ -0,0 +1,115 @@
+// Single responsibility: noticing a statement nobody answered, pooled or on a pin. `statement_timeout`
+// is the server's, so it cannot fire when the server or the path is gone, and the kernel's retransmit
+// window is about 15 minutes. One timer per pool walks the statements in flight; none arms its own.
+
+import type { Scheduler } from '@ultimat3/core';
+import { statementUnanswered } from './errors';
+import { unrefSchedule } from './pool-timer';
+import { statementExcerpt } from './statement-excerpt';
+
+/** Past `statementTimeoutMs` plus this, the server's own bound had to have answered. */
+export const UNANSWERED_GRACE_MS = 5_000;
+export const SWEEP_INTERVAL_MS = 1_000;
+
+export interface PoolSweepOptions<Owner> {
+  /** `statementTimeoutMs + UNANSWERED_GRACE_MS`. The caller skips the sweep when the role has none. */
+  readonly deadlineMs: number;
+  /** A statement on `owner` missed. Called before its caller hears, so a retry finds the new pool. */
+  readonly onMiss: (owner: Owner, excerpt: string, waitedMs: number) => void;
+  readonly schedule?: Scheduler | undefined;
+}
+
+export interface PoolSweep<Owner> {
+  /**
+   * `sending`'s answer, or `X_DB_UNAVAILABLE` once it is past the deadline: the pool's, or
+   * `deadlineMs` for a pin whose own bound moved (`pool-pins.ts`). `0` judges nothing.
+   */
+  track<T>(owner: Owner, text: string, sending: Promise<T>, deadlineMs?: number): Promise<T>;
+}
+
+interface InFlight<Owner> {
+  readonly owner: Owner;
+  readonly text: string;
+  readonly startedAtTick: number;
+  readonly deadlineMs: number;
+  readonly ticksToMiss: number;
+  readonly reject: (reason: unknown) => void;
+}
+
+/**
+ * Age is counted in ticks that FIRED, never read from a clock. The funnel promises a statement no
+ * clock read when nothing observes it (`observe.test.ts`), and the count is also the right answer to
+ * a frozen process: a long GC or a SIGSTOP costs one tick however long it lasted, so answers sitting
+ * unread in their sockets are never judged late. A statement began somewhere inside its first tick,
+ * hence the extra one: nothing is judged before the deadline, and everything within one interval of it.
+ */
+export function poolSweep<Owner>(options: PoolSweepOptions<Owner>): PoolSweep<Owner> {
+  const schedule = options.schedule ?? unrefSchedule;
+  const ticksFor = (deadlineMs: number): number => Math.ceil(deadlineMs / SWEEP_INTERVAL_MS) + 1;
+  const ticksToMiss = ticksFor(options.deadlineMs);
+  // Insertion order is start order and every statement has the same deadline, so a walk stops at
+  // the first one still in time, whatever the pool's size.
+  const inFlight = new Set<InFlight<Owner>>();
+  // Each its own deadline, so walked whole: at most one per pin, and pins are at most `max`.
+  const ownDeadline = new Set<InFlight<Owner>>();
+  let ticks = 0;
+  let armed = false;
+
+  function arm(): void {
+    armed = true;
+    schedule(tick, SWEEP_INTERVAL_MS);
+  }
+
+  function tick(): void {
+    armed = false;
+    ticks += 1;
+    for (const entry of inFlight) {
+      if (ticks - entry.startedAtTick < ticksToMiss) break;
+      miss(inFlight, entry);
+    }
+    for (const entry of ownDeadline) {
+      if (ticks - entry.startedAtTick >= entry.ticksToMiss) miss(ownDeadline, entry);
+    }
+    if (inFlight.size > 0 || ownDeadline.size > 0) arm();
+  }
+
+  function miss(from: Set<InFlight<Owner>>, entry: InFlight<Owner>): void {
+    from.delete(entry);
+    const excerpt = statementExcerpt(entry.text);
+    options.onMiss(entry.owner, excerpt, (ticks - entry.startedAtTick) * SWEEP_INTERVAL_MS);
+    entry.reject(statementUnanswered(excerpt, entry.deadlineMs));
+  }
+
+  return {
+    track<T>(owner: Owner, text: string, sending: Promise<T>, deadlineMs?: number): Promise<T> {
+      if (deadlineMs === 0) return sending;
+      const own = deadlineMs !== undefined && deadlineMs !== options.deadlineMs;
+      const bound = own ? deadlineMs : options.deadlineMs;
+      const into = own ? ownDeadline : inFlight;
+      return new Promise<T>((resolve, reject) => {
+        const entry: InFlight<Owner> = {
+          owner,
+          text,
+          startedAtTick: ticks,
+          deadlineMs: bound,
+          ticksToMiss: own ? ticksFor(bound) : ticksToMiss,
+          reject,
+        };
+        into.add(entry);
+        if (!armed) arm();
+        // Both arms stay attached after a miss: the statement rejects when its pool closes, and
+        // nobody else is left holding that promise.
+        sending.then(
+          (value) => {
+            into.delete(entry);
+            resolve(value);
+          },
+          (error: unknown) => {
+            into.delete(entry);
+            reject(error);
+          },
+        );
+      });
+    },
+  };
+}

package/src/pool-timer.ts

@@ -0,0 +1,10 @@
+// Single responsibility: the timer every pool deadline arms. A deadline guards work in flight, so it
+// must never be the thing keeping a finished process alive.
+
+import type { Scheduler } from '@ultimat3/core';
+
+export const unrefSchedule: Scheduler = (fn, ms) => {
+  const timer = setTimeout(fn, ms);
+  timer.unref?.();
+  return () => clearTimeout(timer);
+};

package/src/pooler-fix.ts

@@ -0,0 +1,53 @@
+// Single responsibility: the instructions a pooler in the path needs, as text with no imports, so
+// `errors.ts`' classifier and the factories over it can both read them without a cycle.
+
+/**
+ * `web`'s numbers, as a command an operator pastes: `<user>` is the one thing this text cannot
+ * know, because per-role bounds mean one database user per role. Through the pooler or direct,
+ * `alter role` is an ordinary statement. A login opened before the `alter` keeps the old values,
+ * which is why reopening is in the comment after `#`, where prose belongs.
+ */
+/**
+ * `DATABASE_URL` with its `options` query parameter cut out, as shell: the pooler refused the
+ * connection for an option in there, so a `psql` that sent it again would fail before `alter role`
+ * ran. Every other parameter (`sslmode`, `application_name`) stays, and only the query is
+ * searched: a password may read `&options=`, the query starts at the first `?`.
+ */
+const PSQL_WITHOUT_OPTIONS = `psql "$(printf '%s' "$DATABASE_URL" | sed -E 's/^([^?]*\\?([^&]*&)*)options=[^&]*(&|$)/\\1/; s/[?&]$//')"`;
+
+const ALTER_ROLE =
+  `${PSQL_WITHOUT_OPTIONS} -c "alter role <user> set statement_timeout = '10s'" ` +
+  `-c "alter role <user> set idle_in_transaction_session_timeout = '30s'"`;
+
+const ALTER_ROLE_NOTE =
+  "<user> is this role's database user, POOL_PROFILES holds every role's numbers; then reopen the pooler's server connections (RECONNECT on its admin console), a role setting applies at login";
+
+/** The two settings the framework itself sends as `options` when no pooler is named. */
+const FRAMEWORK_OPTIONS: ReadonlySet<string> = new Set([
+  'statement_timeout',
+  'idle_in_transaction_session_timeout',
+]);
+
+/**
+ * The fix for a refused startup parameter, decided by which one the pooler named. One of the
+ * framework's own means no pooler is named yet: the switch is the answer. Any other is the
+ * operator's, in `DATABASE_URL`'s `options` — with the switch set the framework sends none, so
+ * naming the switch again would be a loop. A name that is not an identifier is the server's text,
+ * not ours to paste, and is left out.
+ */
+export function poolerOptionsRefusedFix(parameter: string | undefined): string {
+  if (parameter !== undefined && FRAMEWORK_OPTIONS.has(parameter)) {
+    return `export DATABASE_POOLER=transaction && ${ALTER_ROLE}   # session on a session pool; ${ALTER_ROLE_NOTE}`;
+  }
+  const named = parameter !== undefined && /^[a-z_][a-z0-9_.]*$/.test(parameter);
+  const setting = named ? parameter : '<setting>';
+  return `${PSQL_WITHOUT_OPTIONS} -c "alter role <user> set ${setting} = '<value>'"   # then remove -c ${setting}=… from the options of DATABASE_URL, or add it to ignore_startup_parameters of the pooler: a pooler forwards no startup option`;
+}
+
+export const STATEMENT_BOUND_LOST_FIX = `${ALTER_ROLE}   # ${ALTER_ROLE_NOTE}; and export DATABASE_POOLER=transaction (or session) if a pooler sits in the path`;
+
+export const POOLER_SESSION_REQUIRED_FIX =
+  'unset DATABASE_POOLER   # for this role only, and point its DATABASE_URL at the server port rather than the pooler';
+
+export const IDLE_IN_TRANSACTION_FIX =
+  'do slow outbound work before opening the transaction: the server closed it for sitting idle past idleInTransactionMs (POOL_PROFILES), and the await in the handler is the cause, not the connection';