@ultimat3/db 16.0.0 → 18.0.0

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/replica-identity.ts

@@ -0,0 +1,84 @@
+// Single responsibility: the `alter table … replica identity full` a live query needs, emitted once.
+// `@ultimat3/realtime` refuses a subscription to a table without it — logical replication carries no
+// old row on an UPDATE, so no patch can be computed — and which tables need it is a tier-3 fact no
+// entity carries, so it arrives as `GenerateOptions.replicaIdentityFull` and is recorded on the
+// snapshot: the record is what stops the statement being re-emitted on every `x db gen`.
+
+import type { Plan } from './foreign-key-plan';
+import { findTable, type SchemaDescription } from './introspect';
+import { identifier } from './sql';
+
+export interface ReplicaIdentityInput {
+  /** Tables a live query subscribes to. Absent or empty emits nothing and reverts nothing. */
+  readonly wanted: readonly string[] | undefined;
+  /** The tables this migration leaves standing — the ALTER may name no other. */
+  readonly declared: ReadonlySet<string>;
+  /** Of those, the ones it CREATES: their whole `down` is already `drop table`. */
+  readonly created: ReadonlySet<string>;
+  /** What migrations already recorded — `expectedSchema(migrations, ledger)`. */
+  readonly current: SchemaDescription;
+}
+
+/**
+ * Whether the recorded schema already says this table carries it.
+ *
+ * Absent — never `false` — is a sidecar written before the field existed: it declares nothing, so
+ * the ALTER is emitted once more against a table that may already have it, which Postgres accepts.
+ * The opposite reading would be "recorded as not full", and a snapshot that predates the field
+ * cannot mean that. `TableDescription.checks` states the same rule for the same reason.
+ */
+export function recordsReplicaIdentityFull(current: SchemaDescription, table: string): boolean {
+  return findTable(current, table)?.replicaIdentityFull === true;
+}
+
+/** Which tables to record on the snapshot — sorted only by the caller's own table order. */
+function pending(input: ReplicaIdentityInput): readonly string[] {
+  // Deduplicated and sorted, so the same live-query set generates the same bytes whatever order the
+  // manifest walked its queries in: a diff that moves a line is a diff an author has to read.
+  return [...new Set(input.wanted ?? [])]
+    .filter((table) => input.declared.has(table))
+    .filter((table) => !recordsReplicaIdentityFull(input.current, table))
+    .sort();
+}
+
+/**
+ * The tables carrying it once this migration has applied — what `snapshotOf` records.
+ *
+ * The UNION with what is already recorded, never this run's set alone. A caller that passes no
+ * live-query set (`x db gen` from a command that never learned about one) must not silently erase
+ * the fact from the sidecar, or the very next run emits the ALTER again on a table that has it.
+ */
+export function replicaIdentityFullAfter(input: ReplicaIdentityInput): ReadonlySet<string> {
+  const after = new Set<string>();
+  for (const table of input.declared) {
+    if (recordsReplicaIdentityFull(input.current, table)) after.add(table);
+  }
+  for (const table of pending(input)) after.add(table);
+  return after;
+}
+
+/**
+ * Additive only, and never destructive. `alter table … replica identity full` widens what logical
+ * replication carries; it drops no row, rewrites no column and matches none of `destructive.ts`'s
+ * four rules, so the migration it lands in needs no `-- destructive: true` marker.
+ *
+ * A name matching no entity is SKIPPED rather than refused: the list is derived from the manifest's
+ * live queries, and a query whose entity has been deleted is an app fault the generator cannot
+ * repair — emitting the statement anyway would be `42P01` at `ROLE=migrate`, which is the one place
+ * this package refuses to put a fault.
+ *
+ * Nothing is ever reverted. A table dropping out of the live-query set keeps the identity it has:
+ * the option is optional, so "absent" and "no live query subscribes any more" are the same value,
+ * and reading them alike would let a caller that never passes the option turn off replication for
+ * every subscribed table in the app.
+ */
+export function replicaIdentityPlan(plan: Plan, input: ReplicaIdentityInput): void {
+  for (const table of pending(input)) {
+    const name = identifier(table).text;
+    plan.up.push(`alter table ${name} replica identity full;`);
+    // A table this migration created is dropped by its own `down`; a second statement ahead of that
+    // is a line an author reads and nothing performs.
+    if (input.created.has(table)) continue;
+    plan.down.push(`alter table ${name} replica identity default;`);
+  }
+}

package/src/snapshot-parse.ts

@@ -112,11 +112,20 @@ function tableOf(value: unknown): TableDescription | undefined {
   // Absent, never `[]`. A sidecar written before constraints were recorded says nothing about
   // them, and reading that as "this table declares none" would drop every invariant an app has
   // already generated instead of adding the ones its database is missing.
+  // `true` or nothing. `false` is accepted and NORMALISED away rather than rejecting the file: it
+  // is a hand-edit meaning exactly what absence means, and discarding the whole snapshot over it
+  // makes `x db gen` refuse with `X_MIGRATION_SNAPSHOT_MISSING` on a sidecar that says nothing
+  // wrong. Any other value is garbage and takes the file with it, like every field above.
+  const identity = value['replicaIdentityFull'];
+  if (!(identity === undefined || bool(identity))) return undefined;
+  const replica = identity === true ? { replicaIdentityFull: true as const } : {};
   const raw = value['checks'];
-  if (raw === undefined) return { schema, name, columns, primaryKey, indexes, foreignKeys };
+  if (raw === undefined) {
+    return { schema, name, columns, primaryKey, indexes, foreignKeys, ...replica };
+  }
   const checks = all(raw, check);
   if (checks === undefined) return undefined;
-  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks };
+  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks, ...replica };
 }
 
 /**

package/src/sql.ts

@@ -131,6 +131,42 @@ export function identifier(name: string): SqlFragment {
   return raw(`"${name}"`);
 }
 
+/**
+ * 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`,

package/src/statement-funnel.ts

@@ -0,0 +1,101 @@
+// Single responsibility: the pooled driver's statement funnel — one statement on one handle, every
+// driver failure typed on the way out, and the installed `StatementObserver` notified on both
+// settle paths. Split from `client.ts` at the file-size rule; `pglite.ts` holds the mirror pair
+// (`send`/`statement`) for the embedded driver, and the two must keep answering the same way.
+
+import { encodeArrayParameters } from './array-parameter';
+import { statementAttribution } from './attribution';
+import type { BunSqlDriver } from './bun-sql';
+import { driverError } from './errors';
+import { expectedQueryLoopReason } from './expected-loop';
+import { statementObserver } from './observe';
+import type { SqlFragment } from './sql';
+import { withStatementSpan } from './statement-span';
+
+export function rowsOf<T>(result: unknown): readonly T[] {
+  return Array.isArray(result) ? (result as readonly T[]) : [];
+}
+
+// The command tag only when it counted something, exactly like `rowsOf` in `pglite.ts` — one rule
+// across both drivers, so `execute()` and the observer's event cannot answer differently for the
+// same statement depending on which database is behind them. A driver that tags a read `0` while
+// returning rows would otherwise report 0 here and the row count there.
+export function affectedBy(result: unknown): number {
+  if (!Array.isArray(result)) return 0;
+  const count = (result as { count?: unknown }).count;
+  return typeof count === 'number' && count > 0 ? count : result.length;
+}
+
+/** The send itself: one statement on one handle, every driver failure typed on the way out. */
+async function sendOn(
+  driver: Pick<BunSqlDriver, 'unsafe'>,
+  fragment: SqlFragment,
+): Promise<unknown> {
+  try {
+    // `encodeArrayParameters`, never `fragment.values` raw: `Bun.SQL` joins a JS array's elements
+    // with commas, so every `any($n::T[])` in this framework sent Postgres a malformed literal and
+    // failed — the worker's claim loop among them (#384). One encoder here rather than one import
+    // per call site, because this is the only place this driver's `unsafe` is called.
+    return await driver.unsafe(fragment.text, encodeArrayParameters(fragment.values));
+  } catch (error) {
+    // `driverError`, not `dbUnavailable`: the SQLSTATE has always been on this error and nothing
+    // read it, so a `23505` from two clicks racing a signup told the operator the database was
+    // unreachable and paged on-call for an outage that never happened. Everything the table does
+    // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
+    throw driverError(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+  }
+}
+
+/**
+ * The funnel — pooled and pinned statements both arrive here, which is why the observer hangs
+ * off this one function and nowhere else. Uninstalled it costs one property read and one
+ * branch: no clock read, no span, no event object, and `sendOn` receives exactly the call `runOn`
+ * made before the seam existed (axiom 6).
+ */
+export async function runOn(
+  driver: Pick<BunSqlDriver, 'unsafe'>,
+  fragment: SqlFragment,
+): Promise<unknown> {
+  const observer = statementObserver();
+  if (observer === undefined) return sendOn(driver, fragment);
+  // Read here, not by the consumer: the scope is gone by the time a per-request detector judges
+  // what it collected, so the reason has to be captured with the statement it defends.
+  const expected = expectedQueryLoopReason();
+  // Same moment, same argument: `postgresRepo` is several frames and a microtask above this one,
+  // and what it knows — the entity and the operation — is what turns fifty identical `select`s
+  // into "50× findById on members". Absent for hand-written SQL, a migration, a health probe.
+  const attribution = statementAttribution();
+  const started = performance.now();
+  let result: unknown;
+  try {
+    // The span wraps the send and nothing else, so its duration is the statement's and the
+    // observer's own work is not charged to the database.
+    result = await withStatementSpan(fragment.text, () => sendOn(driver, fragment));
+  } catch (error) {
+    // A statement that failed is still a statement: fifty identical timeouts are an N+1 of
+    // timeouts. The error is already `X_DB_UNAVAILABLE`, so the event carries what the caller
+    // is about to be thrown — and an observer that throws here replaces it, which is why
+    // `observe.ts` says a reporting-only observer must not throw.
+    observer.onStatement({
+      text: fragment.text,
+      values: fragment.values,
+      durationMs: performance.now() - started,
+      rows: 0,
+      error,
+      attribution,
+      expected,
+    });
+    throw error;
+  }
+  // Outside the `try` deliberately: a throw from `onStatement` is the observer's, not the
+  // database's, and catching it above would report a statement that succeeded as failed.
+  observer.onStatement({
+    text: fragment.text,
+    values: fragment.values,
+    durationMs: performance.now() - started,
+    rows: affectedBy(result),
+    attribution,
+    expected,
+  });
+  return result;
+}

package/src/ungeneratable.ts

@@ -59,6 +59,17 @@ export const GENERATABLE_FORMS: readonly GeneratableForm[] = [
     name: 'alter column drop expression',
     pattern: /^alter\s+table\s[\s\S]*?\balter\s+column\s[\s\S]*?\bdrop\s+expression\b/,
   },
+  // The form the doc block above calls "the statement that started this", finally on the list:
+  // `GenerateOptions.replicaIdentityFull` emits it `As of 2026-08-26`, so without this entry the
+  // rail reports SQL the generator itself just wrote. Covers `full` and `default` in one phrase —
+  // the down side is as generated as the up side.
+  {
+    name: 'alter table … replica identity full/default',
+    // `full` and `default` ONLY — the two modes `replicaIdentityPlan` emits. `using index` and
+    // `nothing` are hand-written configuration no entity declares, and admitting them here would
+    // read them as generatable and let a squash discard the replication setup in silence.
+    pattern: /^alter\s+table\s[\s\S]*?\breplica\s+identity\s+(?:full|default)\b/,
+  },
 ];
 
 /**