@ultimat3/db 15.0.0 → 17.0.0

package/src/pool-profile.ts

@@ -0,0 +1,125 @@
+// Single responsibility: the five 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.
+
+import { assert, type Role, resolveRole } from '@ultimat3/core';
+import { poolMaxInvalid } from './errors';
+
+export interface PoolProfile {
+  readonly max: number;
+  /** 0 disables the timeout — only `migrate`, which is allowed to take as long as it takes. */
+  readonly statementTimeoutMs: number;
+  readonly idleTimeoutMs: number;
+  /**
+   * How long a statement may **wait for a lock** before `55P03`, distinct from how long it may run.
+   * 0 everywhere but `migrate`, which is the only role that takes `ACCESS EXCLUSIVE`: an `alter
+   * table` queued behind a long `SELECT` puts every later query on that table behind it too,
+   * because Postgres' lock queue is FIFO — and `migrate` runs `statement_timeout = 0`, so nothing
+   * else would ever end the wait. Read by `migrate()` as a `SET LOCAL`, never by the pool.
+   */
+  readonly lockTimeoutMs: number;
+  /**
+   * How long `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.
+   */
+  readonly acquireTimeoutMs: number;
+}
+
+/** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
+export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
+  web: {
+    max: 20,
+    statementTimeoutMs: 10_000,
+    idleTimeoutMs: 30_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 5_000,
+  },
+  sync: {
+    max: 10,
+    statementTimeoutMs: 10_000,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 5_000,
+  },
+  worker: {
+    max: 8,
+    statementTimeoutMs: 120_000,
+    idleTimeoutMs: 30_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 10_000,
+  },
+  scheduler: {
+    max: 2,
+    statementTimeoutMs: 15_000,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 10_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
+  // advisory lock's, and `MIGRATION_LOCK_WAIT_MS` bounds it.
+  migrate: {
+    max: 1,
+    statementTimeoutMs: 0,
+    idleTimeoutMs: 10_000,
+    lockTimeoutMs: 3_000,
+    acquireTimeoutMs: 0,
+  },
+  replicator: {
+    max: 4,
+    statementTimeoutMs: 0,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 0,
+  },
+});
+
+export function poolProfileFor(role: Role = resolveRole()): PoolProfile {
+  return POOL_PROFILES[role];
+}
+
+/** The one pool knob an operator can turn without a rebuild. Layered over the role default. */
+export const POOL_MAX_ENV = 'DATABASE_POOL_MAX';
+
+/**
+ * `DATABASE_POOL_MAX`, or nothing. `POOL_PROFILES` is frozen into the build, so before this the
+ * only way to change a fleet's connection count was to ship a new image — and 400 `web` pods at
+ * `max: 20` is 8,000 backends against a `max_connections` of 450. An unparseable value **refuses**
+ * rather than falling back: a fleet that ignored the number it was given is the failure the
+ * variable exists to prevent, and it would only be found in `pg_stat_activity` at 3am.
+ */
+export function poolMaxFromEnv(): Partial<PoolProfile> {
+  const raw = process.env[POOL_MAX_ENV];
+  if (raw === undefined || raw.trim() === '') return {};
+  const max = Number(raw);
+  if (!Number.isSafeInteger(max) || max < 1) throw poolMaxInvalid(raw);
+  return { max };
+}
+
+/**
+ * The five 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 five 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 three
+ * budgets that document it as "no bound"; `max` is at least one connection, or nothing can run.
+ */
+export function assertPoolProfile(profile: PoolProfile): PoolProfile {
+  const whole = (option: string, value: number, min: 0 | 1): void => {
+    assert(
+      Number.isSafeInteger(value) && value >= min,
+      `pool profile ${option} is ${String(value)}; it must be a whole number of ${min === 1 ? 'at least 1' : '0 or more, where 0 is the documented "no bound"'}`,
+      `pass a whole number for ${option} in createPostgresClient({ profile }), and parse an environment value first — Number(process.env.DATABASE_${option.toUpperCase()} ?? '') is NaN when the variable is unset`,
+    );
+  };
+  whole('max', profile.max, 1);
+  whole('statementTimeoutMs', profile.statementTimeoutMs, 0);
+  whole('idleTimeoutMs', profile.idleTimeoutMs, 0);
+  whole('lockTimeoutMs', profile.lockTimeoutMs, 0);
+  whole('acquireTimeoutMs', profile.acquireTimeoutMs, 0);
+  return profile;
+}

package/src/pool-reserve.ts

@@ -0,0 +1,50 @@
+// Single responsibility: pinning a connection out of the pool under the profile's acquire deadline,
+// and giving back a reservation that arrives after the deadline has passed. Split from `client.ts`,
+// which now asks for a pin rather than owning what "waited too long" means.
+
+import type { BunSqlDriver, BunSqlReserved } from './bun-sql';
+import { poolAcquireTimeout } from './errors';
+import type { PoolProfile } from './pool-profile';
+
+/**
+ * `pool.reserve()` under a deadline. Without one an exhausted pool does not fail, it **queues** —
+ * so a slow endpoint filling all 20 slots turns every later request, `/readyz`'s `select 1`
+ * included, into a wait with no end and no error, and the pod is killed for being unready rather
+ * than answering 503 for the requests it cannot serve.
+ *
+ * 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`.
+ */
+export async function reserveWithin(
+  pool: Pick<BunSqlDriver, 'reserve'>,
+  profile: PoolProfile,
+): Promise<BunSqlReserved> {
+  const budget = profile.acquireTimeoutMs;
+  if (budget <= 0) return pool.reserve();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let expired = false;
+  const pending = pool.reserve();
+  try {
+    return await Promise.race([
+      pending,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          expired = true;
+          reject(poolAcquireTimeout(budget, profile.max));
+        }, budget);
+        // The deadline must not be what keeps a finished process alive.
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    // Attached unconditionally so a rejection arriving after we gave up is handled, not unhandled.
+    void pending.then(
+      (late) => {
+        if (expired) late.release();
+      },
+      () => undefined,
+    );
+  }
+}

package/src/readonly-query.ts

@@ -3,6 +3,7 @@
 // enforcing read-only beats a regex, and the timeout bounds a runaway scan the agent never
 // meant to ask for.
 
+import { finiteCount } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { multipleStatements } from './errors';
 import { identifier, raw, sql } from './sql';
@@ -89,6 +90,26 @@ export async function readOnlyQuery<T>(
   const statements = statementsOf(statement);
   if (statements.length > 1) throw multipleStatements(statement, statements.length);
 
+  // Decided before anything is opened, for the reason `rollback({ steps })` screens before it
+  // takes the advisory lock: a value this build cannot honour is not a fact about the pool. It
+  // was computed after `reserve()` and after `BEGIN READ ONLY`, so an unbounded `timeoutMs`
+  // against an exhausted pool answered with the pool's error — or waited for a connection it was
+  // never going to use — in place of the `X_INVARIANT` naming the option that was wrong.
+  //
+  // Clamped and truncated to an integer: the result is a JS number the caller never touches
+  // as text, so there is nothing here for `raw()` to inject — `SET LOCAL` can't bind `$n`
+  // parameters, which is why this can't go through `sql` the normal, parameterised way.
+  // REFUSED rather than normalised: `NaN` used to take the default silently, so a config typo
+  // ran under a timeout nobody wrote. Only an explicit 0 disables the layer, which is why the
+  // floor is 0 and not 1; the hour ceiling is a clamp on a number that IS one.
+  const asked = finiteCount(
+    'readonlyQuery',
+    'timeoutMs',
+    options.timeoutMs ?? READONLY_TIMEOUT_MS,
+    0,
+  );
+  const ms = Math.min(3_600_000, asked);
+
   const client = options.client ?? baseClient();
   // A pooled BEGIN that lands on a different physical connection than the query that follows is
   // not a transaction at all, so a reservable client must pin one connection for the sequence.
@@ -104,14 +125,6 @@ export async function readOnlyQuery<T>(
     await connection.execute(raw('BEGIN READ ONLY'));
     guards.push('txn:read-only');
 
-    // Clamped and truncated to an integer: the result is a JS number the caller never touches
-    // as text, so there is nothing here for `raw()` to inject — `SET LOCAL` can't bind `$n`
-    // parameters, which is why this can't go through `sql` the normal, parameterised way.
-    // NaN normalises to the default first: only an explicit 0 disables the timeout, and
-    // `Math.min(3_600_000, NaN)` is NaN, which would fail `ms > 0` and silently skip the layer.
-    const asked = options.timeoutMs ?? READONLY_TIMEOUT_MS;
-    const requested = Number.isNaN(asked) ? READONLY_TIMEOUT_MS : asked;
-    const ms = Math.max(0, Math.min(3_600_000, Math.trunc(requested)));
     if (ms > 0) {
       // `LOCAL`, so the setting dies with the transaction — one agent read must not re-time
       // every request the pool serves afterwards. Caveat: embedded PGlite applies the setting

package/src/replica-client.ts

@@ -3,7 +3,7 @@
 // handle a statement is sent on, what happens when the replica will not answer, and the counters
 // that make both visible to a test that cannot scrape a metrics endpoint.
 
-import { type Clock, logger, renderThrowable, systemClock } from '@ultimat3/core';
+import { type Clock, finiteCount, logger, renderThrowable, systemClock } from '@ultimat3/core';
 import { type DbClient, type DbConnection, isReservable, type ReservableClient } from './client';
 import { isPlainRead } from './replica-route';
 import { markScopeWrote, replicaScope } from './replica-scope';
@@ -53,8 +53,21 @@ export function replicatedClient(
   options: ReplicatedClientOptions = {},
 ): ReplicatedClient {
   const clock = options.clock ?? systemClock;
-  const limit = options.breakerFailures ?? BREAKER_FAILURES;
-  const cooldown = options.breakerCooldownMs ?? BREAKER_COOLDOWN_MS;
+  // Both are comparisons and nothing else — `consecutiveFailures >= limit` opens the breaker,
+  // `monotonic() < parkedUntil` holds it open — so a `NaN` in either is a breaker that never trips
+  // and never parks, with every read still going to the replica that is failing.
+  const limit = finiteCount(
+    'replicatedClient',
+    'breakerFailures',
+    options.breakerFailures ?? BREAKER_FAILURES,
+    1,
+  );
+  const cooldown = finiteCount(
+    'replicatedClient',
+    'breakerCooldownMs',
+    options.breakerCooldownMs ?? BREAKER_COOLDOWN_MS,
+    1,
+  );
   let replicaCount = 0;
   let primaryCount = 0;
   let fallbackCount = 0;

package/src/retype-keys.ts

@@ -0,0 +1,139 @@
+// Single responsibility: which columns this migration RETYPES, and which recorded FOREIGN KEYS
+// that breaks — the one answer to both, computed over the whole schema and above `diffTable`.
+//
+// **Why above `diffTable`, and not inside it like every other dependent.** Postgres re-checks a
+// key's two ends against each other on every `alter column … type` and cannot rebuild one whose
+// sides stopped matching: measured on 18.4, `42804 foreign key constraint "rk_posts_org_code_fkey"
+// cannot be implemented — Key columns "org_code" … and "code" … are of incompatible types: integer
+// and text`, thrown by the ALTER itself, inside `ROLE=migrate`, with the ledger recording nothing.
+// The constraint that breaks is recorded on the table that OWNS it, which for a retype of the
+// key's TARGET is a different entity's record — `diffTable(orgs)` is handed `orgs`'s row and can
+// never see `posts.foreignKeys`. So the retype set is derived once, from `entities` and `current`
+// together, and `retypeColumn` READS it rather than deciding again: two answers to "is this column
+// being retyped" is the axiom-1 split this package has spent the week closing.
+//
+// **Over-approximated on purpose, the rule `retype-dependents.ts` states.** Whether two types keep
+// an equality operator between them is operator resolution, which is exactly the knowledge a
+// generator with no database cannot have — `varchar(80)` and `text` share one, `integer` and
+// `text` do not. A key moved aside that did not need to be is one `add constraint` re-validating a
+// table the ALTER beside it is already rewriting under ACCESS EXCLUSIVE; a key missed is the
+// release phase failing with the server's words and none of the entity's.
+//
+// **What it cannot see.** A key the recorded schema does not hold — a hand-written migration's,
+// or one from a sidecar written before `foreignKeys` was recorded — is invisible here and still
+// `42804`, the same construction limit `x db gen` has against a hand-added expression index. And
+// re-adding the key is still the SERVER's judgement: an entity that retypes one end and not the
+// other declares a pairing Postgres has no operator for, and the `add constraint` at the end of
+// `up` is where that is said. Refusing it here would need the type knowledge two paragraphs up.
+
+import type { EntityDescriptionLike } from './entity-shape';
+import { addForeignKey, dropForeignKey, keyId, unrestorableNote } from './foreign-key';
+import type { Plan } from './foreign-key-plan';
+import { isGenerated } from './generated-column';
+import type { ForeignKeyDescription, SchemaDescription, TableDescription } from './introspect';
+import { findTable } from './introspect';
+import { sqlType } from './sql-type';
+
+/** Table name to the columns whose physical type this migration moves. Empty entries are omitted. */
+export type RetypedColumns = ReadonlyMap<string, ReadonlySet<string>>;
+
+/** The columns of one table this migration retypes — `retypeColumn`'s own read of the set above. */
+export function retypedIn(retyped: RetypedColumns, table: string): ReadonlySet<string> {
+  return retyped.get(table) ?? new Set<string>();
+}
+
+/**
+ * Every plain `alter column … type` this migration will emit, before any of them is written.
+ *
+ * A GENERATED column is deliberately absent: `generated-column.ts` owns every statement one of
+ * them produces, and its plain -> generated path is a `drop column` that takes the key with it
+ * rather than an ALTER that trips over it. That gap is real and is named in `generated-column.ts`.
+ */
+export function retypedColumns(
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+): RetypedColumns {
+  const moved = new Map<string, ReadonlySet<string>>();
+  for (const entity of entities) {
+    const live = findTable(current, entity.table);
+    if (live === undefined) continue;
+    const recorded = new Map(live.columns.map((column) => [column.name, column]));
+    const columns = new Set<string>();
+    for (const column of entity.columns) {
+      const held = recorded.get(column.column);
+      if (held === undefined) continue;
+      if (isGenerated(column) || held.generated !== undefined) continue;
+      if (held.dataType !== sqlType(column.kind)) columns.add(column.column);
+    }
+    if (columns.size > 0) moved.set(entity.table, columns);
+  }
+  return moved;
+}
+
+/** Whether either end of `key` sits on a column this migration retypes. `owner` owns the key. */
+function breaksOn(key: ForeignKeyDescription, owner: string, retyped: RetypedColumns): boolean {
+  const own = retyped.get(owner);
+  if (own !== undefined && key.columns.some((column) => own.has(column))) return true;
+  const target = retyped.get(key.referencedTable);
+  return target !== undefined && key.referencedColumns.some((column) => target.has(column));
+}
+
+/**
+ * Drop every recorded key a retype breaks, restore it in `down`, and answer which names were moved.
+ *
+ * The two statements go in the plan's OWN buckets and not beside the ALTER, because the drop has
+ * to precede every alter in the migration and the restore has to follow every one of them — both
+ * ends of a key can move, in two different entities' diffs. `preAlters` is merged at the very top
+ * of `up` and at the very FRONT of `down`, which reversal turns into the very end: so the reversed
+ * script reads drop-the-new-key, retype both ends back, add the recorded key. Restoring it any
+ * earlier is `42804` in the other direction.
+ *
+ * What comes back in `up` is not written here at all: `foreignKeyPlan` reads the returned set,
+ * treats a moved key as one the schema does not record, and adds the DECLARED key in the
+ * `constraints` bucket that already runs after every table statement. That is what makes the three
+ * outcomes fall out of code that already exists — still declared (added back), no longer declared
+ * (gone, exactly as the removal arm would have left it), and declared with a new `on delete` rule
+ * (added back carrying it) — instead of three branches restating them here.
+ */
+export function moveKeysAside(
+  current: SchemaDescription,
+  retyped: RetypedColumns,
+  doomed: ReadonlySet<string>,
+  preAlters: Plan,
+): ReadonlySet<string> {
+  const moved = new Set<string>();
+  for (const table of current.tables) {
+    for (const key of table.foreignKeys) {
+      if (!breaksOn(key, table.name, retyped)) continue;
+      moved.add(keyId(table.name, key.name));
+      preAlters.up.push(dropForeignKey(table.name, key.name));
+      preAlters.down.push(restore(table, key, doomed));
+    }
+  }
+  return moved;
+}
+
+/**
+ * The `down` half. A key whose own table or whose target is being dropped has no `add constraint`
+ * that could run at all, so it gets the SAME note `unrestorableDrop` gives one — the text is
+ * `unrestorableNote`'s, in `foreign-key.ts`, and not a second spelling here. One failed rollback
+ * has one wording whichever module emitted it (axiom 2); these two had already drifted, this one
+ * naming no table at all while `foreign-key-plan.ts` named the target.
+ *
+ * The table it names is the key's OWN when that is the one going: a constraint whose table is
+ * gone is the more proximate reason there is nothing to add it back onto.
+ */
+function restore(
+  table: TableDescription,
+  key: ForeignKeyDescription,
+  doomed: ReadonlySet<string>,
+): string {
+  if (!doomed.has(table.name) && !doomed.has(key.referencedTable)) {
+    return addForeignKey(table.name, key);
+  }
+  return unrestorableNote(
+    table.name,
+    key.name,
+    doomed.has(table.name) ? table.name : key.referencedTable,
+  );
+}

package/src/sql-type.ts

@@ -0,0 +1,35 @@
+// Single responsibility: the physical Postgres type a declared column KIND becomes. One table, so
+// the statement that writes a column, the snapshot that records it and the pass that decides
+// whether a retype is happening at all cannot disagree about what `char` means.
+//
+// Split out of `generate.ts` for `retype-keys.ts`, which has to answer "does this column's type
+// move" ABOVE `diffTable` — a foreign key over a retyped column lives in another table's record.
+
+const SQL_TYPES: Readonly<Record<string, string>> = {
+  uuid: 'uuid',
+  text: 'text',
+  // Bare `char` is `char(1)` in Postgres, and the only column carrying this kind is money's
+  // currency — a three-letter ISO 4217 code whose CHECK the entity emits on the same line.
+  // Without the length no currency ever fits the constraint the same statement demands.
+  char: 'char(3)',
+  boolean: 'boolean',
+  integer: 'integer',
+  bigint: 'bigint',
+  numeric: 'numeric',
+  timestamptz: 'timestamptz',
+  date: 'date',
+  jsonb: 'jsonb',
+};
+
+/**
+ * A kind this table does not name passes through verbatim — an app's own domain, an enum type a
+ * hand-written migration created.
+ *
+ * `Object.hasOwn` and not a bare index: `kind` is DATA, so `SQL_TYPES['constructor']` answered the
+ * `Object` function and `type ${wanted}` spliced its source into a statement, while `'__proto__'`
+ * answered `[object Object]`. Guarded, both behave like every other unknown kind and pass through
+ * as themselves. Measured across the package's 766 tests: no other input's answer moves.
+ */
+export function sqlType(kind: string): string {
+  return Object.hasOwn(SQL_TYPES, kind) ? (SQL_TYPES[kind] ?? kind) : kind;
+}

package/src/sql.ts

@@ -132,19 +132,73 @@ export function identifier(name: string): SqlFragment {
 }
 
 /**
- * A quoted string literal. Postgres utility statements (`CREATE DATABASE`, `COMMENT ON`) reject
- * bound parameters, so this is the only place a value may be inlined — and it escapes quotes.
- * Never reach for it in a query: `sql` binds parameters there.
+ * The two characters a shell substitutes INSIDE double quotes. Rejected before `identifier` is
+ * consulted at all, because `identifier` accepts both.
+ */
+const SHELL_ACTIVE = /[`$]/;
+
+/**
+ * A quoted identifier that is ALSO inert wherever a human pastes it — or `null` for a name no line
+ * built here may spell. The one screen a catalog name goes through before it reaches a `fix:`.
+ *
+ * TWO layers, and `identifier` closes only the first. It answers about SQL: it refuses `"`, `\`
+ * and whitespace, and ACCEPTS a backtick and a `$` — `SAFE_IDENTIFIER` above allows `$` on its
+ * fast path — which are exactly the two characters `$(…)` and a command substitution are built
+ * from. A column called `$(id)` inside `x db gen "add $(id)"` therefore RUNS `id` the moment its
+ * reader pastes the line, and a screen reusing `identifier` unchanged would ship a green suite
+ * over that.
+ *
+ * The name is DATA at every caller: `create table "x""; drop table users; --" ("id" int)` is legal
+ * DDL, so whoever can create a table or a column picks the text that lands in a `fix:`. A refusal
+ * is degraded to prose by its caller and never escaped — the argument to `x db gen` is a migration
+ * DESCRIPTION, not an identifier, so there is no quoted form that makes a hostile name safe to
+ * pass, and a fix naming no command beats one running a second command the reader never read.
+ *
+ * `'` is deliberately NOT refused: it is legal in an identifier and inert both in a psql session
+ * and inside shell double quotes. The price of the two that ARE refused is a legal `a$b` losing
+ * its executable fix line, which is prose in place of something nobody read running.
+ */
+export function shellInertIdentifier(name: string): string | null {
+  if (SHELL_ACTIVE.test(name)) return null;
+  try {
+    return identifier(name).text;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A quoted string literal Postgres reads IDENTICALLY under both settings of
+ * `standard_conforming_strings`. Utility and DDL statements (`CREATE DATABASE`, `COMMENT ON`,
+ * `create table … default …`) reject bound parameters, so this is the only place a value may be
+ * inlined. Never reach for it in a query: `sql` binds parameters there.
+ *
+ * **It DOES receive caller input, and this comment said otherwise until 2026-08-25.**
+ * `column-default.ts:43` renders `ColumnDefaultLike` here, which is an app's own
+ * `.default('C:\\logs')` crossing the tier seam from `@ultimat3/entity` — nothing validates it and
+ * no `identifier()` guards it. (The package's two other callers are safe by CONSTRUCTION, not by
+ * input: `readonly-role.ts:71` sits in the same `sql` template as an `identifier(role)` that throws
+ * first, and `branch.ts:85` runs after an already-awaited `identifier(base)`.)
+ *
+ * Doubling the quote is not the whole rule. That GUC is settable per session, per database and per
+ * role and `SET` needs no privilege, and with it `off` a backslash escapes the character after it
+ * inside an ordinary `'…'`. Measured on 18.4 through `generateMigration`: `.default('C:\\logs')`
+ * emits `default 'C:\logs'`, which stores `C:\logs` with the GUC on and **`C:logs`** with it off —
+ * a column defaulting to a value nobody wrote, with no error anywhere. A value ENDING in a
+ * backslash is worse than wrong: the escaped quote leaves the literal unterminated and the text
+ * after it is string data until the next `'` puts the remainder back into code position.
  *
- * The doubling is only an escape while `standard_conforming_strings` is `on`, which has been the
- * server default since 9.1: with it OFF, a backslash escapes the quote that follows and a value
- * ending in one closes the literal early. So this is safe for framework-supplied names — a
- * database, a schema, a comment this repo writes — and is NOT an escape for untrusted text under
- * an arbitrary server configuration. Nothing passes it caller input today; if something must,
- * bind a parameter instead, or send `E''`-style quoting from a statement that can take one.
+ * `E'…'` fixes the dialect in the text itself rather than trusting a setting, so both readings
+ * agree — **only** when the value actually carries a backslash. Without one there is no escape
+ * mechanism for the two settings to disagree about, so every migration already generated stays byte
+ * for byte what it was and nothing regenerates spuriously; both tracked apps have applied
+ * migrations on disk with hashes over this text. Same rule, same measurement, as
+ * `packages/entity/src/sql-literal.ts`, which is where it was first written and which adopts this
+ * one — tier 1 holds it, tier 2 imports down.
  */
 export function literal(value: string): SqlFragment {
-  return raw(`'${value.replaceAll("'", "''")}'`);
+  const quoted = value.replaceAll("'", "''");
+  return raw(value.includes('\\') ? `E'${quoted.replaceAll('\\', '\\\\')}'` : `'${quoted}'`);
 }
 
 /** `a, b, c` — the one blessed way to build an IN list or a column list. */