@ultimat3/db 11.3.0 → 13.0.0

package/src/replica-route.ts

@@ -0,0 +1,60 @@
+// Single responsibility: may THIS statement be served by a replica. An allow-list with a refusal
+// list under it, whose default is the primary — the opposite bias to the `readonly.ts` lexer this
+// package deleted, and the reason that deletion does not forbid this file.
+
+import { statementVerb } from './statement-shape';
+
+export type DbNode = 'primary' | 'replica';
+
+/**
+ * The only verbs a replica may be offered. `with` is here because a CTE read is the shape half the
+ * framework's paginated queries take, and `WRITE_WORD` below is what tells `with … select` from
+ * `with … update … returning` — which `statementKind()` calls a read, and is exactly why that
+ * function is not the authority here.
+ */
+const READ_VERBS: ReadonlySet<string> = new Set(['select', 'table', 'values']);
+const CTE_VERB = 'with';
+
+/**
+ * A word that disqualifies the whole statement. Matched with word boundaries against the raw
+ * lowercased text — NOT against `stripSqlNoise`'d text, deliberately: a `;`-in-a-literal is data
+ * and must not split a statement, but a `'update'` in a literal costing one read its replica is a
+ * false positive on the SAFE side, and blanking every statement on the hot path to buy back that
+ * one read is a cost axiom 6 refuses. `share` covers `for share` and `for key share`; `update`
+ * covers `for update` and `for no key update`; `into` covers `select … into`, which creates a table.
+ */
+const WRITE_WORD =
+  /\b(?:insert|update|delete|merge|truncate|copy|create|drop|alter|grant|revoke|call|do|lock|share|refresh|reindex|vacuum|analyze|set|reset|begin|commit|rollback|savepoint|into)\b/;
+
+/**
+ * Function names a word boundary cannot reach — `pg_advisory_lock` has a `_` before `advisory`, so
+ * `\badvisory\b` never matches it. Every one of these either writes or mutates session state that
+ * belongs to whichever backend ran it, and a standby accepts them silently rather than answering
+ * `25006`, so the server's own refusal cannot be the safety net here the way it is for a real write.
+ */
+const UNSAFE_CALLS: readonly string[] = [
+  'nextval',
+  'setval',
+  'set_config',
+  'advisory',
+  'dblink',
+  'lo_import',
+  'lo_export',
+  'pg_export_snapshot',
+  'pg_replication',
+  'pg_create',
+];
+
+/**
+ * Provably a plain read, or `false`. Never "probably": everything this cannot vouch for is the
+ * primary's, so a statement shape nobody anticipated costs a replica opportunity and never a wrong
+ * answer. That inversion is the whole difference from `readonly.ts`, whose 22-word deny-list read
+ * `select pg_sleep(60)` as safe because the default was permission.
+ */
+export function isPlainRead(text: string): boolean {
+  const lowered = text.toLowerCase();
+  const verb = statementVerb(lowered);
+  if (!READ_VERBS.has(verb) && verb !== CTE_VERB) return false;
+  if (WRITE_WORD.test(lowered)) return false;
+  return !UNSAFE_CALLS.some((call) => lowered.includes(call));
+}

package/src/replica-scope.ts

@@ -0,0 +1,54 @@
+// Single responsibility: the scope inside which a read may be served by a replica, and the one bit
+// that closes read-your-writes — has this scope written yet. A mutable value on an async context,
+// the same shape `transaction.ts` uses for `TxState.live`, so a write at any depth and across any
+// `await` is seen by every later read in the same scope.
+
+import { asyncContext } from '@ultimat3/core';
+
+/**
+ * Deliberately mutable, and deliberately not `readonly`. The whole mechanism is that a write ten
+ * frames and three `await`s below the scope's opener flips this, and the read after it sees it —
+ * a fresh object per statement could not carry that, and threading a parameter would be the same
+ * fact written at every call site, with every path an author forgot serving a stale row.
+ */
+export interface ReplicaScope {
+  wrote: boolean;
+}
+
+const scope = asyncContext<ReplicaScope>('the replica read scope');
+
+/**
+ * Declare that reads inside `fn` may be served by a replica — until `fn` writes, after which every
+ * read in it is the primary's for the rest of the scope.
+ *
+ * **Opt-in, and that is the safety argument, not an ergonomic one.** `packages/db` cannot see a
+ * request boundary: `@ultimat3/http`'s pipeline opens the `Ctx` and nothing tells this tier when a
+ * request ended, so a write-marker keyed on `Ctx.requestId` would be a `Map` that only grows —
+ * ~100 bytes per request, forever — and any eviction policy that forgets a request that WROTE
+ * serves it a stale row, which is worse than the capacity problem replicas exist to solve. With no
+ * scope open nothing routes and the client is byte-identical to a single-pool one, so the failure
+ * mode of "nobody opened one" is today's behaviour rather than a wrong answer.
+ *
+ * Nesting is one scope, not two: an inner `withReplicaReads` inside a scope that has already
+ * written must not un-write it. The innermost call reuses the store it finds.
+ */
+export function withReplicaReads<T>(fn: () => T): T {
+  const open = scope.get();
+  if (open !== undefined) return fn();
+  return scope.run({ wrote: false }, fn);
+}
+
+/** The scope in flight, or `undefined` — which is every caller that never opened one. */
+export function replicaScope(): ReplicaScope | undefined {
+  return scope.get();
+}
+
+/**
+ * Record that this scope has written. Called for every statement that is not provably a plain read
+ * — including `begin`, a `set`, and anything the router could not classify — because the direction
+ * that is safe to be wrong in is "assume it wrote". A no-op outside a scope, where nothing routes.
+ */
+export function markScopeWrote(): void {
+  const open = scope.get();
+  if (open !== undefined) open.wrote = true;
+}

package/src/snapshot-parse.ts

@@ -36,13 +36,19 @@ function column(value: unknown): ColumnDescription | undefined {
 
 function index(value: unknown): IndexDescription | undefined {
   if (!isRow(value)) return undefined;
-  const { name, columns, unique, primary, where, order: direction } = value;
+  const { name, columns, unique, primary, where, order: direction, using } = value;
   if (!str(name) || !strings(columns) || !bool(unique) || !bool(primary)) return undefined;
   // Written by 1.2.0 onwards. A sidecar from before it carries neither, and the total, ascending
   // reading is what that generation actually emitted — so an older file stays readable rather
   // than being discarded whole, which would refuse to generate against every existing app.
   if (!(where === undefined || nullableStr(where))) return undefined;
   if (!(direction === undefined || order(direction))) return undefined;
+  // Any string, not the closed set. The live side of this type is the CATALOG's, which answers
+  // `gist` and an extension's own access method, and a sidecar recording one must round-trip so
+  // drift can report it — the refusal belongs at generation, where `declaredMethod` names the
+  // method and the fix, not here, where it would discard the whole snapshot without saying which
+  // field was wrong. Absent stays absent: `indexMethodOf` reads it as the btree it always was.
+  if (!(using === undefined || str(using))) return undefined;
   return {
     name,
     columns,
@@ -50,6 +56,7 @@ function index(value: unknown): IndexDescription | undefined {
     primary,
     where: where === undefined ? null : where,
     order: direction === undefined ? null : direction,
+    ...(using === undefined ? {} : { using }),
   };
 }
 

package/src/transaction.ts

@@ -7,6 +7,7 @@ import type { Random } from '@ultimat3/core';
 import { assert, asyncContext, nanoid } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { isolationLevelInvalid, serializationExhausted } from './errors';
+import { markScopeWrote } from './replica-scope';
 import { raw, type SqlFragment } from './sql';
 import { isRetryableState } from './sqlstate';
 import { serializationRetryDelayMs } from './transaction-backoff';
@@ -206,6 +207,11 @@ async function runNested<T>(outer: TxState, fn: (tx: DbTx) => Promise<T>): Promi
  */
 async function runRoot<T>(fn: (tx: DbTx) => Promise<T>, options: TransactionOptions): Promise<T> {
   const client = options.client ?? baseClient();
+  // A transaction is assumed to write unless it said otherwise, so every read AFTER it in the same
+  // `withReplicaReads` scope is the primary's. The pin below already keeps the transaction's own
+  // statements off any replica — this is about the rest of the request, which `replica-client.ts`
+  // could not otherwise see: `runRoot` sends through a reserved connection, not through the router.
+  if (options.readOnly !== true) markScopeWrote();
   // A pooled BEGIN that lands on a different physical connection than the statements after it is
   // not a transaction at all, so a reservable client pins one connection for the whole scope.
   // Held by a `using` declaration rather than a `finally`, because a `finally` only covers what