@ultimat3/db 15.0.0 → 17.0.0

package/src/client.ts

@@ -1,17 +1,20 @@
-// Single responsibility: the Postgres connection and the ambient `db()` handle. Pool size and
-// statement timeout are chosen by runtime ROLE — a `worker` draining a queue must not size its
-// pool like a `web` process behind a CDN. `Bun.SQL` is reached lazily so importing this module
-// never opens a socket (the CLI imports it to print help).
+// Single responsibility: the pooled Postgres client and the ambient `db()` handle — one statement
+// funnel, the reserved-connection pin, and the process-wide client every repository reaches
+// through. Sizing lives in `pool-profile.ts`, the connection string in `connection-url.ts`, the
+// `Bun.SQL` slice in `bun-sql.ts`, so importing this module never opens a socket.
 
-import { type Role, renderThrowable, resolveRole } from '@ultimat3/core';
+import { type Role, resolveRole } from '@ultimat3/core';
 import { statementAttribution } from './attribution';
+import { type BunSqlDriver, type BunSqlReserved, bunSqlFactory } from './bun-sql';
+import { connectionUrl } from './connection-url';
 // Deliberate cycle, the same shape as `client.ts ⇄ transaction.ts`: nothing here is referenced at
 // module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
 import { defaultClient } from './default-client';
-import { DbError, dbUnavailable, driverError, poolAcquireTimeout, poolMaxInvalid } from './errors';
+import { DbError, driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
-import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
 import { statementObserver } from './observe';
+import { assertPoolProfile, type PoolProfile, poolProfileFor } from './pool-profile';
+import { reserveWithin } from './pool-reserve';
 import { type SqlFragment, sql } from './sql';
 import { withStatementSpan } from './statement-span';
 import { currentTx } from './transaction';
@@ -41,123 +44,6 @@ export function isReservable(client: DbClient): client is ReservableClient {
   return typeof (client as Partial<ReservableClient>).reserve === 'function';
 }
 
-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 };
-}
-
-/** One connection pinned out of `Bun.SQL`'s pool, released back by hand. */
-interface BunSqlReserved {
-  unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
-  release(): void;
-}
-
-/** The slice of `Bun.SQL` we use. Declared structurally so this package has no dependency. */
-interface BunSqlDriver {
-  unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
-  reserve(): Promise<BunSqlReserved>;
-  close(options?: { readonly timeout?: number }): Promise<void>;
-}
-
-type BunSqlFactory = new (url: string, options?: Readonly<Record<string, unknown>>) => BunSqlDriver;
-
-function bunSqlFactory(): BunSqlFactory {
-  const host = globalThis as unknown as { readonly Bun?: { readonly SQL?: unknown } };
-  const factory = host.Bun?.SQL;
-  if (typeof factory !== 'function') {
-    throw dbUnavailable('Bun.SQL is unavailable — this package requires Bun >= 1.3');
-  }
-  return factory as BunSqlFactory;
-}
-
 export interface PostgresClientOptions {
   readonly url?: string | undefined;
   readonly role?: Role | undefined;
@@ -165,46 +51,6 @@ export interface PostgresClientOptions {
   readonly applicationName?: string | undefined;
 }
 
-function connectionUrl(options: PostgresClientOptions, profile: PoolProfile): string {
-  const raw = options.url ?? process.env['DATABASE_URL'];
-  if (raw === undefined || raw === '') {
-    throw dbUnavailable('DATABASE_URL is not set, so there is no database to connect to');
-  }
-  let url: URL;
-  try {
-    url = new URL(raw);
-  } catch (error) {
-    throw dbUnavailable(`DATABASE_URL is not a valid url: ${raw}`, error);
-  }
-  // libpq `options` is the portable way to pin a statement timeout for every pooled connection —
-  // MERGED into the operator's own, never assigned over it, and emitted for every role including
-  // the two whose bound is 0. `set` here dropped a `?options=-c search_path=app` on `web`, `sync`,
-  // `worker` and `scheduler` and kept it on `migrate` and `replicator`, so the role that runs the
-  // migrations and the role that serves the traffic read different schemas. 0 is a value, not a
-  // silence: it is `migrate` saying it may take as long as it takes, and left unsaid a server-side
-  // `alter database ... set statement_timeout` kills the one role that must outlive it.
-  // `application_name` is a LABEL, not a bound: 'ultimate' is a DEFAULT, and a default may not
-  // overwrite what the operator wrote — `?application_name=billing-api` is the filter their
-  // `pg_stat_activity` query, their pooler rule and their audit rule all match on, and losing it
-  // is silent. Both spellings count, or the URL parameter and a `-c application_name=` in
-  // `options` disagree and which one the backend honours is argument order nobody here measured.
-  const named = options.applicationName;
-  const settings: Record<string, string> = {
-    statement_timeout: String(profile.statementTimeoutMs),
-  };
-  const inOptions = declaresLibpqOption(url.searchParams.get('options'), 'application_name');
-  // An explicit `applicationName` is a deliberate call by the role that opened the pool, so it
-  // wins. Only then is the setting named to the merge, and only when the operator wrote the other
-  // spelling: `mergeLibpqOptions` drops their assignment before appending, so the two cannot
-  // disagree — and a URL with no assignment in it keeps the exact `options` it always had.
-  if (named !== undefined && inOptions) settings['application_name'] = named;
-  const declared = url.searchParams.has('application_name') || inOptions;
-  url.searchParams.set('options', mergeLibpqOptions(url.searchParams.get('options'), settings));
-  if (named !== undefined) url.searchParams.set('application_name', named);
-  else if (!declared) url.searchParams.set('application_name', 'ultimate');
-  return url.toString();
-}
-
 function rowsOf<T>(result: unknown): readonly T[] {
   return Array.isArray(result) ? (result as readonly T[]) : [];
 }
@@ -219,49 +65,6 @@ function affectedBy(result: unknown): number {
   return typeof count === 'number' && count > 0 ? count : result.length;
 }
 
-/**
- * `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`.
- */
-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,
-    );
-  }
-}
-
 export interface PostgresClient extends ReservableClient {
   readonly profile: PoolProfile;
   ping(): Promise<void>;
@@ -271,7 +74,10 @@ export interface PostgresClient extends ReservableClient {
 /** Lazily connects: the pool opens on the first statement, never at import. */
 export function createPostgresClient(options: PostgresClientOptions = {}): PostgresClient {
   const role = options.role ?? resolveRole();
-  const profile: PoolProfile = { ...poolProfileFor(role), ...(options.profile ?? {}) };
+  const profile: PoolProfile = assertPoolProfile({
+    ...poolProfileFor(role),
+    ...(options.profile ?? {}),
+  });
   let driver: BunSqlDriver | undefined;
 
   function connect(): BunSqlDriver {
@@ -455,27 +261,3 @@ export function baseClient(): DbClient {
 export function db(): DbClient {
   return currentTx() ?? baseClient();
 }
-
-/** Named `Db*` because `@ultimat3/core` already exports a `HealthReport` for the lifecycle. */
-export interface DbHealthReport {
-  readonly ok: boolean;
-  readonly latencyMs: number;
-  readonly error?: string | undefined;
-}
-
-/** Backs `/readyz` for every role. Never throws — the probe wants a report, not an exception. */
-export async function checkDb(client: DbClient = baseClient()): Promise<DbHealthReport> {
-  const started = performance.now();
-  try {
-    await client.query(sql`select 1`);
-    return { ok: true, latencyMs: Math.round(performance.now() - started) };
-  } catch (error) {
-    return {
-      ok: false,
-      latencyMs: Math.round(performance.now() - started),
-      // `renderThrowable`, never `error.message`: the probe wants a report, and a render that
-      // throws is an exception out of `/readyz` — the one caller that cannot catch it.
-      error: renderThrowable(error),
-    };
-  }
-}

package/src/connection-url.ts

@@ -0,0 +1,60 @@
+// Single responsibility: turning `DATABASE_URL` plus a resolved pool profile into the connection
+// string the driver opens — the libpq `options` merge and the `application_name` label. Split from
+// `client.ts` because which settings reach a connection is a rule, not a step of connecting.
+
+import { describeValue } from '@ultimat3/core';
+import { dbUnavailable } from './errors';
+import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
+import type { PoolProfile } from './pool-profile';
+
+export interface ConnectionUrlOptions {
+  readonly url?: string | undefined;
+  readonly applicationName?: string | undefined;
+}
+
+export function connectionUrl(options: ConnectionUrlOptions, profile: PoolProfile): string {
+  const raw = options.url ?? process.env['DATABASE_URL'];
+  if (raw === undefined || raw === '') {
+    throw dbUnavailable('DATABASE_URL is not set, so there is no database to connect to');
+  }
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch (error) {
+    // The SHAPE of the rejected value, never the value. A connection string is
+    // `user:password@host` by construction, and this `cause` is the boot log line AND the `--json`
+    // payload — the logger redacts `fields` by key, so a password baked into a message has no key
+    // left to redact it by. `@ultimat3/core`'s `defineEnv` reached the identical conclusion about
+    // the identical variable (`packages/core/src/env.ts`); this is the same rule at the second
+    // reader, not a second rule. The value still has a printer: `x env check`, through
+    // `maskedEnvValues`.
+    throw dbUnavailable(`DATABASE_URL is not a valid url: received ${describeValue(raw)}`, error);
+  }
+  // libpq `options` is the portable way to pin a statement timeout for every pooled connection —
+  // MERGED into the operator's own, never assigned over it, and emitted for every role including
+  // the two whose bound is 0. `set` here dropped a `?options=-c search_path=app` on `web`, `sync`,
+  // `worker` and `scheduler` and kept it on `migrate` and `replicator`, so the role that runs the
+  // migrations and the role that serves the traffic read different schemas. 0 is a value, not a
+  // silence: it is `migrate` saying it may take as long as it takes, and left unsaid a server-side
+  // `alter database ... set statement_timeout` kills the one role that must outlive it.
+  // `application_name` is a LABEL, not a bound: 'ultimate' is a DEFAULT, and a default may not
+  // overwrite what the operator wrote — `?application_name=billing-api` is the filter their
+  // `pg_stat_activity` query, their pooler rule and their audit rule all match on, and losing it
+  // is silent. Both spellings count, or the URL parameter and a `-c application_name=` in
+  // `options` disagree and which one the backend honours is argument order nobody here measured.
+  const named = options.applicationName;
+  const settings: Record<string, string> = {
+    statement_timeout: String(profile.statementTimeoutMs),
+  };
+  const inOptions = declaresLibpqOption(url.searchParams.get('options'), 'application_name');
+  // An explicit `applicationName` is a deliberate call by the role that opened the pool, so it
+  // wins. Only then is the setting named to the merge, and only when the operator wrote the other
+  // spelling: `mergeLibpqOptions` drops their assignment before appending, so the two cannot
+  // disagree — and a URL with no assignment in it keeps the exact `options` it always had.
+  if (named !== undefined && inOptions) settings['application_name'] = named;
+  const declared = url.searchParams.has('application_name') || inOptions;
+  url.searchParams.set('options', mergeLibpqOptions(url.searchParams.get('options'), settings));
+  if (named !== undefined) url.searchParams.set('application_name', named);
+  else if (!declared) url.searchParams.set('application_name', 'ultimate');
+  return url.toString();
+}

package/src/db-health.ts

@@ -0,0 +1,31 @@
+// Single responsibility: the database's readiness answer — one `select 1` timed and reported, never
+// thrown. Split from `client.ts` because a probe's report is a different job from opening a pool,
+// and every role's `/readyz` reads this one and nothing else of the client.
+
+import { renderThrowable } from '@ultimat3/core';
+import { baseClient, type DbClient } from './client';
+import { sql } from './sql';
+
+/** Named `Db*` because `@ultimat3/core` already exports a `HealthReport` for the lifecycle. */
+export interface DbHealthReport {
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  readonly error?: string | undefined;
+}
+
+/** Backs `/readyz` for every role. Never throws — the probe wants a report, not an exception. */
+export async function checkDb(client: DbClient = baseClient()): Promise<DbHealthReport> {
+  const started = performance.now();
+  try {
+    await client.query(sql`select 1`);
+    return { ok: true, latencyMs: Math.round(performance.now() - started) };
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: Math.round(performance.now() - started),
+      // `renderThrowable`, never `error.message`: the probe wants a report, and a render that
+      // throws is an exception out of `/readyz` — the one caller that cannot catch it.
+      error: renderThrowable(error),
+    };
+  }
+}

package/src/default-client.ts

@@ -3,7 +3,8 @@
 // framework decides a process's database topology from the environment, and `client.ts` is at the
 // line ceiling.
 
-import { createPostgresClient, type DbClient, poolMaxFromEnv } from './client';
+import { createPostgresClient, type DbClient } from './client';
+import { poolMaxFromEnv } from './pool-profile';
 import { replicatedClient } from './replica-client';
 
 /**

package/src/dependent-view.ts

@@ -0,0 +1,224 @@
+// Single responsibility: refuse a migration whose `alter column … type` a VIEW is compiled against,
+// before the statement is sent — and name the view, the column and the statement that recreates it.
+//
+// **This is the honest ceiling for views, and the reason it is not in the generator.** `x db gen`
+// runs with no database open; `SchemaDescription` has no field for a view; `introspect()` reads
+// none by construction (`app-relation.ts` excludes every non-table relation); and no `entity()` can
+// declare one. So nothing the generator reads knows a view exists, and a `GenerateOptions.views`
+// with no caller to fill it is the declared-and-never-wired defect this release exists to
+// eliminate. What DOES have a connection is `migrate()`, one statement before the abort — and the
+// catalog answers the question exactly, including for a view no migration in this repo wrote.
+//
+// Measured on 18.4: `alter table "dv_docs" alter column "rank" type text using "rank"::text` under
+// a view selecting that column answers `0A000 cannot alter type of a column used by a view or
+// rule`, with `rule _RETURN on view dv_docs_published depends on column "rank"` in a DETAIL field
+// nothing printed — surfaced as `X_DB_UNAVAILABLE: cannot reach the database`, whose registered
+// `fix:` says to set `DATABASE_URL`.
+//
+// It does not repair anything and does not claim to: the deploy still stops. What it replaces is
+// wrong advice about a healthy database with the two statements that unblock it.
+
+import type { DbClient } from './client';
+import { migrationViewDepends } from './migration-errors';
+import { identifier, join, sql } from './sql';
+import { IDENTIFIER_PART, noiseAt } from './sql-scan';
+import { statementsOf } from './statement-split';
+
+/** One `alter table <table> alter column <column> type …`, as the catalog spells both names. */
+export interface RetypeTarget {
+  readonly table: string;
+  readonly column: string;
+}
+
+/**
+ * One name in a statement. Called a WORD and not the obvious lexer noun deliberately:
+ * `scripts/secret-compare.ts` reads a comparison whose operand is NAMED like a credential, and
+ * that noun is one of the names it reads — a `.text === spelling` under it is indistinguishable
+ * from an auth check to a static rule that has only the name to go on.
+ */
+interface SqlWord {
+  readonly text: string;
+  /** A quoted name is never a keyword — `"type"` is a column called type, not the clause. */
+  readonly quoted: boolean;
+}
+
+/**
+ * The names in one statement, in order, folded the way Postgres folds them: an unquoted identifier
+ * to lower case, a quoted one verbatim. Comments, string literals and dollar-quoted bodies
+ * contribute nothing, through this package's one lexer — `-- alter column` is prose and
+ * `'alter column'` is data.
+ */
+function wordsOf(statement: string): readonly SqlWord[] {
+  const words: SqlWord[] = [];
+  let at = 0;
+  while (at < statement.length) {
+    const noise = noiseAt(statement, at);
+    if (noise !== null) {
+      if (noise.kind === 'identifier') {
+        words.push({ text: statement.slice(at + 1, noise.end - 1), quoted: true });
+      }
+      at = noise.end;
+      continue;
+    }
+    if (!IDENTIFIER_PART.test(statement[at] ?? '')) {
+      at += 1;
+      continue;
+    }
+    let end = at;
+    while (end < statement.length && IDENTIFIER_PART.test(statement[end] ?? '')) end += 1;
+    words.push({ text: statement.slice(at, end).toLowerCase(), quoted: false });
+    at = end;
+  }
+  return words;
+}
+
+const keyword = (word: SqlWord | undefined, spelling: string): boolean =>
+  word !== undefined && !word.quoted && word.text === spelling;
+
+/**
+ * Every column this script retypes. Narrow ON PURPOSE — `alter table <t> … alter [column] <c> type`
+ * and nothing else — because a miss costs exactly what happens today (the server's own `0A000`,
+ * one statement later) while a false positive costs a catalog read and a refusal on a migration
+ * that would have applied. Every retype `generateMigration` emits is this shape; a hand-written
+ * `ALTER TABLE ONLY t …` is not, and is deliberately left to the server.
+ */
+export function retypeTargets(script: string): readonly RetypeTarget[] {
+  const targets: RetypeTarget[] = [];
+  for (const statement of statementsOf(script)) {
+    const words = wordsOf(statement);
+    const table = words[2];
+    if (!keyword(words[0], 'alter') || !keyword(words[1], 'table') || table === undefined) {
+      continue;
+    }
+    for (let index = 3; index < words.length; index += 1) {
+      if (!keyword(words[index], 'alter')) continue;
+      const at = keyword(words[index + 1], 'column') ? index + 2 : index + 1;
+      const column = words[at];
+      if (column === undefined || !keyword(words[at + 1], 'type')) continue;
+      targets.push({ table: table.text, column: column.text });
+    }
+  }
+  return targets;
+}
+
+interface ViewRow {
+  readonly view_name: string;
+  readonly table_name: string;
+  readonly column_name: string;
+  readonly definition: string;
+  /** `v` or `m`. A MATERIALISED view needs different DDL to drop and to recreate. */
+  readonly relkind: string;
+}
+
+/**
+ * `pg_depend` -> `pg_rewrite` is the only edge that records this: a view depends on a column
+ * through its `_RETURN` rule, never through a row in `pg_class` alone. Materialised views are
+ * included (`relkind = 'm'`) because they carry the same rule and fail the same way.
+ *
+ * One round trip for every target, `in` over both name lists, and the exact pairing filtered in
+ * the caller — a per-target query would be a loop of statements inside the migration's own
+ * transaction, and a cross-product read is cheap where a false pair is not.
+ */
+async function dependentViews(
+  client: DbClient,
+  targets: readonly RetypeTarget[],
+): Promise<readonly ViewRow[]> {
+  const tables = join(
+    [...new Set(targets.map((target) => target.table))].map((name) => sql`${name}`),
+  );
+  const columns = join(
+    [...new Set(targets.map((target) => target.column))].map((name) => sql`${name}`),
+  );
+  return client.query<ViewRow>(sql`
+    select distinct v.relname as view_name, c.relname as table_name, a.attname as column_name,
+           pg_get_viewdef(v.oid, true) as definition, v.relkind as relkind
+      from pg_depend d
+      join pg_rewrite r on r.oid = d.objid and d.classid = 'pg_rewrite'::regclass
+      join pg_class v on v.oid = r.ev_class
+      join pg_class c on c.oid = d.refobjid and d.refclassid = 'pg_class'::regclass
+      join pg_attribute a on a.attrelid = c.oid and a.attnum = d.refobjsubid
+     where v.relkind in ('v', 'm') and v.oid <> c.oid
+       and c.relname in (${tables}) and a.attname in (${columns})
+     order by v.relname
+  `);
+}
+
+/**
+ * One SQL statement as a single argv word for `psql -c`.
+ *
+ * SINGLE quotes, unlike `migrationConflict`'s `-c "…"`: `identifier()` writes the view's name in
+ * DOUBLE quotes, so a double-quoted shell word would end at the name. The definition is the
+ * server's own text and may hold a `'` of its own — `where status = 'published'` — so the one
+ * escape a POSIX shell has for it is spelled out here. This is not the SQL literal escape
+ * (`sql.ts`'s `literal()`, the tree's one copy of that); nothing below is sent to a server.
+ */
+const shellArg = (statement: string): string => `'${statement.replaceAll("'", `'\\''`)}'`;
+
+/** The invocation `migrationConflict` already writes, with the statement as its own argv word. */
+const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
+
+/**
+ * The two statements that unblock the deploy, as one line an operator pastes.
+ *
+ * It leads with the command to RUN and carries the follow-up in a `#` comment, the shape
+ * `migrateConcurrent` and `migrationSnapshotMissing` already write. It used to lead with bare DDL
+ * and a `#`: `#` is not a comment in Postgres, so psql read the whole line and failed on it, while
+ * a shell read `drop` as a program that does not exist. Neither reader could run it (axiom 4).
+ *
+ * `identifier()` REFUSES a name holding a quote, a space or a backslash — all three legal inside a
+ * quoted Postgres name — and a `fix:` may not throw: the rule `rebuildForeignKey` already states,
+ * with the same shape. A refusal that raised `X_SQL_UNSAFE` in place of the finding would hand the
+ * operator an exception where a verdict was asked for, over a view name that is perfectly legal.
+ * The fallback still leads with a command that runs — a psql session — because quoting that name
+ * is the one step this package will not do twice: `identifier()` is its only identifier writer.
+ *
+ * The definition is collapsed to one line because `pg_get_viewdef(oid, true)` pretty-prints across
+ * several and a `fix:` is read as a command.
+ *
+ * `relkind` decides the DDL and is not cosmetic: `dependentViews` deliberately selects `'m'` as
+ * well as `'v'`, and Postgres refuses `drop view` on a materialised one — `WRONG_OBJECT_TYPE`,
+ * "use DROP MATERIALIZED VIEW". So the one case the query went out of its way to include was the
+ * one whose `fix:` could not run. `pg_get_viewdef` answers the SELECT for both kinds, so only the
+ * two keywords differ; a matview's indexes and its `WITH DATA` population are NOT carried, and
+ * the fix says so rather than implying the recreate is complete.
+ */
+function restoreView(view: string, definition: string, relkind: string): string {
+  const body = definition.replace(/\s+/g, ' ').replace(/;\s*$/, '').trim();
+  const materialised = relkind === 'm';
+  const kind = materialised ? 'materialized view' : 'view';
+  const note = materialised
+    ? '   # then re-create its indexes: a matview keeps none of them across a drop'
+    : '';
+  try {
+    const name = identifier(view).text;
+    return (
+      `${psql(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
+      `${psql(`create ${kind} ${name} as ${body}`)}${note}`
+    );
+  } catch {
+    return (
+      `psql "$DATABASE_URL"   # quote the ${kind} name ${JSON.stringify(view)} yourself, then: ` +
+      `drop ${kind} <name>; \\q; x db migrate; and create it again as: create ${kind} <name> as ${body}${note}`
+    );
+  }
+}
+
+/**
+ * Refuse before the ALTER, or return having sent nothing at all. A script that retypes no column
+ * costs one text scan and no round trip, which is every migration an app writes that is not a
+ * retype.
+ */
+export async function refuseDependentViews(client: DbClient, script: string): Promise<void> {
+  const targets = retypeTargets(script);
+  if (targets.length === 0) return;
+  const wanted = new Set(targets.map((target) => `${target.table}.${target.column}`));
+  for (const row of await dependentViews(client, targets)) {
+    if (!wanted.has(`${row.table_name}.${row.column_name}`)) continue;
+    throw migrationViewDepends(
+      row.view_name,
+      row.table_name,
+      row.column_name,
+      restoreView(row.view_name, row.definition, row.relkind),
+    );
+  }
+}

package/src/drift-errors.ts

@@ -0,0 +1,36 @@
+// Single responsibility: the `X_DB_DRIFT` constructor — the error form of the finding
+// `drift-findings.ts`'s `unexpectedColumn` reports, thrown where a caller has no report to hand
+// back. Split out of `errors.ts` for the import it needs and nothing else: the fix line puts a
+// column name into a shell command, so it screens through `shellInertIdentifier` (`sql.ts`) —
+// and `sql.ts` imports `errors.ts`, so this cannot live there without a cycle around the module
+// whose evaluation registers every code. The code is still declared, titled and registered in
+// `errors.ts`, exactly as `migration-errors.ts` and `invariant-errors.ts` are.
+
+import { DbError } from './errors';
+import { shellInertIdentifier } from './sql';
+
+/**
+ * The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync; that
+ * one screens the column through the same `@ultimat3/db` export, so the two lines are the same
+ * text on both sides of the tier seam.
+ *
+ * The column name is the CATALOG's, so it is data: whoever can add a column picks the text that
+ * lands here, and `x db gen "add C"` puts it inside SHELL DOUBLE QUOTES, where `$(…)` and a
+ * backtick substitute before `x` is reached at all. The argument is a migration DESCRIPTION and
+ * not an identifier, so no quoted form makes a hostile name safe to pass — a name the screen
+ * refuses is left OUT of the command rather than escaped into it. The command still runs and
+ * still generates the migration; the name is read off `cause` and `meta`, which are prose nobody
+ * pastes.
+ */
+export const dbDrift = (tableName: string, columnName: string): DbError =>
+  new DbError({
+    code: 'X_DB_DRIFT',
+    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
+    fix:
+      shellInertIdentifier(columnName) === null
+        ? 'x db gen "add the column named in this error"   # its name carries a backtick, a ' +
+          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
+          'this command'
+        : `x db gen "add ${columnName}"`,
+    meta: { table: tableName, column: columnName },
+  });