@ultimat3/db 29.4.0 → 30.0.0

package/src/retired.ts

@@ -0,0 +1,131 @@
+// Single responsibility: what `entity({ retired: [...] })` means to `x db gen`. A retired column has
+// left the entity, so nothing in the new release reads it, and stays in the table and the snapshot,
+// so the old release keeps working. Retiring writes a marker and no statement; the drop comes in a
+// later migration, by the ordinary arm, which only then finds the column it may take.
+
+import { columnCheckNameOf } from './check-ddl';
+import type { EntityDescriptionLike } from './entity-shape';
+import { foreignKeysOf, type Plan } from './foreign-key-plan';
+import type { ColumnDescription, SchemaDescription, TableDescription } from './introspect';
+import { findTable } from './introspect';
+import { contractsMarker, retiresMarker, unretiresMarker } from './rolling';
+import {
+  retiredColumnReferenced,
+  retiredColumnRequired,
+  retiredNameUnknown,
+} from './rolling-errors';
+import { retiredKeyIndexes } from './same-tenant';
+import { identifier } from './sql';
+
+/** The names, as `retiresMarker` writes them: through `identifier()`, which refuses a quote. */
+const bare = (name: string): string => identifier(name).text.slice(1, -1);
+
+/** The line above a retired column's drop, which is what `retireAndContractPending` pairs up. */
+export const contractsMarkerFor = (table: string, column: string): string =>
+  contractsMarker(bare(table), bare(column));
+
+/**
+ * Refuse what cannot be retired, and mark what newly is. Marker-only by design: indexes, foreign
+ * keys and the column's own CHECK stay until the drop takes them with the column.
+ *
+ * Also the way back: a retired column declared again gets a marker of its own, because the only
+ * thing that moved is the snapshot and an empty `up` writes no file (`generateAppMigration`) — the
+ * flag would stay on the record, and a later removal would read as retired when it never was.
+ */
+export function retirePlan(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: Plan,
+  entities: readonly EntityDescriptionLike[],
+): void {
+  const pointedAt = new Set(
+    entities
+      .flatMap(foreignKeysOf)
+      .filter((key) => key.referencedTable === entity.table)
+      .flatMap((key) => key.referencedColumns),
+  );
+  const recorded = new Map(live.columns.map((column) => [column.name, column]));
+  const declared = new Set(entity.columns.map((column) => column.column));
+  for (const name of entity.retired ?? []) {
+    const column = recorded.get(name);
+    if (column === undefined || declared.has(name)) {
+      throw retiredNameUnknown(entity.name, entity.table, name);
+    }
+    // Declared keys, not recorded ones: a key this same migration lets go is no obstacle.
+    if (pointedAt.has(name)) throw retiredColumnReferenced(entity.name, entity.table, name);
+    if (column.retired === true) continue;
+    const fillable = column.nullable || column.default !== null || column.generated !== undefined;
+    if (!fillable || live.primaryKey.includes(name)) {
+      throw retiredColumnRequired(entity.name, entity.table, name);
+    }
+    plan.up.push(retiresMarker(bare(entity.table), bare(name)));
+  }
+  for (const column of live.columns) {
+    if (column.retired === true && declared.has(column.name)) {
+      plan.up.push(unretiresMarker(bare(entity.table), bare(column.name)));
+    }
+  }
+}
+
+function recordInTable(
+  table: TableDescription,
+  live: TableDescription,
+  entity: EntityDescriptionLike,
+): TableDescription {
+  const names = new Set(entity.retired ?? []);
+  const over = (columns: readonly string[]): boolean => columns.some((each) => names.has(each));
+  const kept: ColumnDescription[] = live.columns
+    .filter((column) => names.has(column.name))
+    .map((column) => ({ ...column, retired: true }));
+  const columns = [...table.columns, ...kept]
+    .sort((a, b) => (a.name < b.name ? -1 : 1))
+    .map((column, index) => ({ ...column, position: index + 1 }));
+  const checkNames = new Set([...names].map((name) => columnCheckNameOf(entity.table, name)));
+  const checks = [
+    ...(table.checks ?? []),
+    ...(live.checks ?? []).filter((check) => checkNames.has(check.name)),
+  ];
+  return {
+    ...table,
+    columns,
+    indexes: [...table.indexes, ...live.indexes.filter((index) => over(index.columns))],
+    foreignKeys: [
+      ...table.foreignKeys,
+      ...live.foreignKeys.filter((key) => over(key.columns)),
+    ].sort((a, b) => (a.name < b.name ? -1 : 1)),
+    ...(checks.length === 0 ? {} : { checks }),
+  };
+}
+
+/**
+ * `snapshotOf` carried one step on: what declarations alone cannot say, read off the recorded
+ * schema. One function for both readers, `x db gen` and the `drift` step, because the second asks
+ * whether the first would write anything: two answers would be drift on a correct app.
+ */
+export function recordRetired(
+  snapshot: SchemaDescription,
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+): SchemaDescription {
+  const retiring = new Map(
+    entities
+      .filter((entity) => (entity.retired ?? []).length > 0)
+      .map((entity) => [entity.table, entity]),
+  );
+  if (retiring.size === 0) return snapshot;
+  const keptIndexes = retiredKeyIndexes(entities, current);
+  return {
+    ...snapshot,
+    tables: snapshot.tables.map((recorded) => {
+      const known = new Set(recorded.indexes.map((index) => index.name));
+      const kept = (keptIndexes.get(recorded.name) ?? []).filter((index) => !known.has(index.name));
+      const table =
+        kept.length === 0 ? recorded : { ...recorded, indexes: [...recorded.indexes, ...kept] };
+      const entity = retiring.get(table.name);
+      const live = findTable(current, table.name);
+      return entity === undefined || live === undefined
+        ? table
+        : recordInTable(table, live, entity);
+    }),
+  };
+}

package/src/retype-dependents.ts

@@ -102,6 +102,8 @@ export function retypeDependents(column: string, live: TableDescription): Retype
 export interface MovedAside {
   readonly indexes: Set<string>;
   readonly checks: Set<string>;
+  /** Columns whose default the retype already moved, so the in-place arm has nothing to do. */
+  readonly defaults: Set<string>;
 }
 
 /**

package/src/rolling-errors.ts

@@ -0,0 +1,97 @@
+// Single responsibility: every way `X_MIGRATION_ROLLING_UNSAFE` is raised, and the path each one
+// prints. One code, because all of them are one fact: the previous release is still running. Apart
+// from `migration-errors.ts` for its size, and because this one reads `rolling.ts`'s vocabulary.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { DbError } from './errors';
+import type { RetireAndContract, RollingUnsafeStatement } from './rolling';
+
+const CODE = 'X_MIGRATION_ROLLING_UNSAFE';
+
+/**
+ * The path, whole, once. Followed verbatim it ends with the column gone and neither release ever
+ * having read a column that was not there (`retired.live.test.ts`). Every name is from a sidecar,
+ * an entity or a migration's text, so it reaches the command through the shell screen.
+ */
+function twoReleases(entity: string, column: string): string {
+  const c = renderFixShellArg(column, '<column>');
+  return (
+    `entity('${renderFixShellArg(entity, '<entity>')}', { retired: ['${c}'] })   # then x db gen "retire ${c}", deploy, ` +
+    `then remove it from retired and x db gen "drop ${c}" --allow-destructive`
+  );
+}
+
+/** `x db gen`: a column left the entity with no `retired` in between. */
+export const columnDropNotRetired = (
+  entity: string,
+  table: string,
+  column: string,
+  migration: string,
+): DbError =>
+  new DbError({
+    code: CODE,
+    cause:
+      `dropping "${table}"."${column}" in the release that stops declaring it fails every read and ` +
+      'insert of the pods still running the previous release, which name it (X_DB_SCHEMA_STALE)',
+    fix: `${twoReleases(entity, column)} — one instance that stops before the next starts: x db gen ${renderFixShellArg(migration, '<name>')} --allow-destructive --rolling-unsafe`,
+    meta: { table, column },
+  });
+
+/** `retired` names what no migration recorded, or a column the entity still declares. */
+export const retiredNameUnknown = (entity: string, table: string, column: string): DbError =>
+  new DbError({
+    code: CODE,
+    cause: `entity "${entity}" retires "${column}", and "${table}" records no such column to retire, or still declares it`,
+    fix: `entity('${renderFixShellArg(entity, '<entity>')}', { retired: [] })   # drop "${renderFixShellArg(column, '<column>')}" from retired: list only a column the newest migration records and columns no longer declares`,
+    meta: { table, column },
+  });
+
+/** The new release omits it from every insert, so the database must be able to fill it. */
+export const retiredColumnRequired = (entity: string, table: string, column: string): DbError =>
+  new DbError({
+    code: CODE,
+    cause:
+      `"${table}"."${column}" is NOT NULL with no default or part of the primary key, so an ` +
+      'insert from the release that retires it would fail: that release no longer writes it',
+    fix: `${renderFixShellArg(column, '<column>')}: text().nullable()   # on entity('${renderFixShellArg(entity, '<entity>')}'), then x db gen "relax ${renderFixShellArg(column, '<column>')}", deploy, then retire it`,
+    meta: { table, column },
+  });
+
+/** The drop this retire promises would be `2BP01` at apply, so it is refused while it is cheap. */
+export const retiredColumnReferenced = (entity: string, table: string, column: string): DbError =>
+  new DbError({
+    code: CODE,
+    cause: `"${table}"."${column}" is the target of a foreign key an entity still declares, so the drop that follows this retire could never apply (2BP01)`,
+    fix: `references(() => target.id)   # repoint or remove every references() to "${renderFixShellArg(column, '<column>')}" of entity('${renderFixShellArg(entity, '<entity>')}'), then x db gen`,
+    meta: { table, column },
+  });
+
+const STATED: Readonly<Record<RollingUnsafeStatement['kind'], string>> = {
+  'drop-column': 'drops a column no earlier migration retired',
+  'rename-column': 'renames a column the previous release still names',
+  'rename-table': 'renames a table the previous release still names',
+};
+
+/** The gate's half, over a committed file. One per migration, as `migrationDestructive` is. */
+export const migrationRollingUnsafe = (
+  file: string,
+  first: RollingUnsafeStatement,
+  more = 0,
+): DbError =>
+  new DbError({
+    code: CODE,
+    cause: `${file} ${STATED[first.kind]}${more === 0 ? '' : ` (and ${more} more)`}: ${first.statement}`,
+    fix: `${twoReleases(first.table, first.column ?? '<column>')} — one instance that stops before the next starts: add the line "-- rolling-unsafe: true" to ${file} before it is applied`,
+    meta: { file, kind: first.kind, table: first.table, column: first.column },
+  });
+
+/** `migrate()`, before the first BEGIN: both are fine, both in one deploy is not. */
+export const retireAndContractTogether = (pair: RetireAndContract): DbError =>
+  new DbError({
+    code: CODE,
+    cause:
+      `migrations "${pair.retire}" and "${pair.contract}" retire and drop "${pair.table}"."${pair.column}" in ` +
+      'one deploy, so the pods of the release before them meet the drop; nothing was applied',
+    fix: `git log --oneline -- packages/db/migrations   # deploy the build whose newest migration is the retire, then this one`,
+    meta: { retire: pair.retire, contract: pair.contract },
+  });

package/src/rolling.ts

@@ -0,0 +1,212 @@
+// Single responsibility: decide whether a migration's `up` would break the pods still running the
+// old release, and read the markers that say a drop took two releases. `destructive.ts`'s shape,
+// and the same path: `statementsOf`, then lexical. A rolling deploy runs N and N-1 at once, and N-1
+// names every column it declares in every statement, so a drop before it is gone is an outage.
+
+import { REBUILDABLE_DROP_CLAUSES } from './destructive';
+import { markerLines } from './marker-line';
+import { noiseAt } from './sql-scan';
+import { statementExcerpt } from './statement-excerpt';
+import { statementsOf } from './statement-split';
+
+/** The line a migration carries when one instance stops before the next starts. */
+export const ROLLING_UNSAFE_MARKER = '-- rolling-unsafe: true';
+
+const ROLLING_UNSAFE_COMMENT = /^--[ \t]*rolling-unsafe:[ \t]*true[ \t]*\r?\n?$/i;
+
+export const hasRollingUnsafeMarker = (sql: string): boolean =>
+  markerLines(sql, ROLLING_UNSAFE_COMMENT).length > 0;
+
+/**
+ * Spelled through `identifier()` by every writer (`retired.ts`), so the comment holds no newline and
+ * no second quote for a reader to trip on, and this one reads back exactly what was written.
+ */
+const quotedPair = (table: string, column: string): string => `"${table}"."${column}"`;
+export const retiresMarker = (table: string, column: string): string =>
+  `-- retires ${quotedPair(table, column)}`;
+export const contractsMarker = (table: string, column: string): string =>
+  `-- contracts ${quotedPair(table, column)}`;
+export const unretiresMarker = (table: string, column: string): string =>
+  `-- unretires ${quotedPair(table, column)}`;
+
+const namedBy = (verb: string): RegExp =>
+  new RegExp(`^--[ \\t]*${verb}[ \\t]+"([^"]+)"\\."([^"]+)"[ \\t]*\\r?\\n?$`, 'i');
+
+const RETIRES = namedBy('retires');
+const CONTRACTS = namedBy('contracts');
+const UNRETIRES = namedBy('unretires');
+
+/** One column as one string, for a set: compared, never parsed, and no two pairs share one. */
+export const columnKey = (table: string, column: string): string => JSON.stringify([table, column]);
+
+interface NamedColumn {
+  readonly table: string;
+  readonly column: string;
+}
+
+function columnsNamedBy(sql: string, marker: RegExp): readonly NamedColumn[] {
+  return markerLines(sql, marker).flatMap((line) => {
+    const match = marker.exec(line);
+    const [table, column] = [match?.[1], match?.[2]];
+    return table === undefined || column === undefined ? [] : [{ table, column }];
+  });
+}
+
+/** The columns this `up` declares retired, as `columnKey`. */
+export const retiredColumnsIn = (up: string): readonly string[] =>
+  columnsNamedBy(up, RETIRES).map(({ table, column }) => columnKey(table, column));
+
+/** The columns this `up` takes back: a retire before it earns no later drop. */
+export const unretiredColumnsIn = (up: string): readonly string[] =>
+  columnsNamedBy(up, UNRETIRES).map(({ table, column }) => columnKey(table, column));
+
+/** The closed list. A rail that tried every Postgres foot-gun would be a second SQL parser. */
+export type RollingUnsafeKind = 'drop-column' | 'rename-column' | 'rename-table';
+
+export interface RollingUnsafeStatement {
+  readonly kind: RollingUnsafeKind;
+  readonly table: string;
+  /** The column, or the table's old name for `rename-table`, which has no column. */
+  readonly column: string | null;
+  /** The statement as written, on one line. */
+  readonly statement: string;
+}
+
+/**
+ * Words, quoted identifiers and punctuation, with comments, literals and dollar bodies gone. Why
+ * not `stripSqlNoise`, which `destructive.ts` reads: it blanks a quoted identifier too, and this
+ * rail has to say WHICH column.
+ */
+function tokensOf(statement: string): readonly string[] {
+  let text = '';
+  let index = 0;
+  while (index < statement.length) {
+    const noise = noiseAt(statement, index);
+    if (noise === null) {
+      text += statement[index];
+      index += 1;
+      continue;
+    }
+    if (noise.kind === 'identifier') text += statement.slice(index, noise.end);
+    else text += noise.kind.endsWith('comment') ? ' ' : " '' ";
+    index = noise.end;
+  }
+  return text.match(/"(?:[^"]|"")*"|[A-Za-z_][\w$]*|\S/g) ?? [];
+}
+
+const isWord = (lexeme: string | undefined, word: string): boolean =>
+  lexeme !== undefined && !lexeme.startsWith('"') && lexeme.toLowerCase() === word;
+
+/** What Postgres folds a token to: a quoted one keeps its case, a bare one lowers. */
+const nameOf = (token: string): string =>
+  token.startsWith('"') ? token.slice(1, -1).replaceAll('""', '"') : token.toLowerCase();
+
+/** `alter table [if exists] [only] [schema.]t`, as the table and where its subcommands start. */
+function alteredTable(tokens: readonly string[]): { table: string; next: number } | undefined {
+  if (!isWord(tokens[0], 'alter') || !isWord(tokens[1], 'table')) return undefined;
+  let at = 2;
+  if (isWord(tokens[at], 'if') && isWord(tokens[at + 1], 'exists')) at += 2;
+  if (isWord(tokens[at], 'only')) at += 1;
+  let name = tokens[at];
+  at += 1;
+  while (tokens[at] === '.') {
+    name = tokens[at + 1];
+    at += 2;
+  }
+  return name === undefined ? undefined : { table: nameOf(name), next: at };
+}
+
+/** Top-level commas only: `add constraint … (a, b)` is one subcommand. */
+function subcommands(tokens: readonly string[]): readonly (readonly string[])[] {
+  const parts: string[][] = [[]];
+  let depth = 0;
+  for (const token of tokens) {
+    if (token === '(') depth += 1;
+    if (token === ')') depth -= 1;
+    if (token === ',' && depth === 0) parts.push([]);
+    else parts.at(-1)?.push(token);
+  }
+  return parts;
+}
+
+function judged(
+  table: string,
+  part: readonly string[],
+): { readonly kind: RollingUnsafeKind; readonly column: string | null } | undefined {
+  const [verb, second] = part;
+  if (isWord(verb, 'drop')) {
+    if (second === undefined || REBUILDABLE_DROP_CLAUSES.includes(second.toLowerCase()))
+      return undefined;
+    let at = isWord(second, 'column') ? 2 : 1;
+    if (isWord(part[at], 'if') && isWord(part[at + 1], 'exists')) at += 2;
+    const name = part[at];
+    return name === undefined ? undefined : { kind: 'drop-column', column: nameOf(name) };
+  }
+  if (!isWord(verb, 'rename') || second === undefined) return undefined;
+  if (isWord(second, 'to')) return { kind: 'rename-table', column: table };
+  if (isWord(second, 'constraint')) return undefined;
+  const name = isWord(second, 'column') ? part[2] : second;
+  return name === undefined ? undefined : { kind: 'rename-column', column: nameOf(name) };
+}
+
+/**
+ * Every statement in `up` a pod of the previous release would still trip over, in apply order.
+ *
+ * `retired` holds the columns an EARLIER migration marked, as `columnKey`: a drop of one of those
+ * is what the two-release path is for. A retire in the same file is not earlier, since one deploy
+ * would apply both. Only `up`, the rule `destructive.ts` states.
+ */
+export function rollingUnsafeStatements(
+  up: string,
+  retired: ReadonlySet<string> = new Set(),
+): readonly RollingUnsafeStatement[] {
+  const found: RollingUnsafeStatement[] = [];
+  for (const statement of statementsOf(up)) {
+    const tokens = tokensOf(statement);
+    const altered = alteredTable(tokens);
+    if (altered === undefined) continue;
+    for (const part of subcommands(tokens.slice(altered.next))) {
+      const verdict = judged(altered.table, part);
+      if (verdict === undefined) continue;
+      if (
+        verdict.kind === 'drop-column' &&
+        verdict.column !== null &&
+        retired.has(columnKey(altered.table, verdict.column))
+      ) {
+        continue;
+      }
+      found.push({
+        kind: verdict.kind,
+        table: altered.table,
+        column: verdict.column,
+        statement: statementExcerpt(statement),
+      });
+    }
+  }
+  return found;
+}
+
+export interface RetireAndContract {
+  readonly table: string;
+  readonly column: string;
+  readonly retire: string;
+  readonly contract: string;
+}
+
+/**
+ * The pair the static rail cannot see: both written properly in separate migrations, and both about
+ * to land in one deploy, where old pods meet the drop anyway. The first such pair, or `undefined`.
+ */
+export function retireAndContractPending(
+  pending: readonly { readonly id: string; readonly up: string }[],
+): RetireAndContract | undefined {
+  const retires = new Map<string, string>();
+  for (const migration of pending) {
+    for (const { table, column } of columnsNamedBy(migration.up, CONTRACTS)) {
+      const retire = retires.get(columnKey(table, column));
+      if (retire !== undefined) return { table, column, retire, contract: migration.id };
+    }
+    for (const key of retiredColumnsIn(migration.up)) retires.set(key, migration.id);
+  }
+  return undefined;
+}

package/src/row-secure-client.ts

@@ -0,0 +1,54 @@
+// Single responsibility: with row security on, no statement reaches the database outside a
+// transaction that carries the tenant. A statement sent bare — a raw `sql`, a report, a repository
+// read — is wrapped in one: BEGIN, the tenant's `set_config`, the statement, COMMIT.
+
+import type { DbClient } from './client';
+import { isPlainRead } from './replica-route';
+import type { SqlFragment } from './sql';
+import { statementVerb } from './statement-shape';
+import { currentTx, withTransaction } from './transaction';
+import { transactionSettings } from './transaction-settings';
+
+const SENDS: ReadonlySet<PropertyKey> = new Set(['query', 'one', 'execute']);
+
+/**
+ * A transaction's own control statements, sent by `withTransaction` on a client it could not pin
+ * (a non-reservable one sends BEGIN through this very proxy): wrapping those would nest a second
+ * transaction around the first one's BEGIN.
+ */
+const CONTROL: ReadonlySet<string> = new Set([
+  'begin',
+  'commit',
+  'rollback',
+  'savepoint',
+  'release',
+]);
+
+/**
+ * `inner`, every other member untouched (`close`, `listen`, `profile`, `reserve`), with its three
+ * sends wrapped. The accepted cost — a transaction per bare statement — is paid only when the
+ * provider has a tenant to set; with none the statement goes as it came and the policy, reading an
+ * unset tenant, answers no rows. A statement already inside a transaction is that transaction's.
+ */
+export function rowSecureClient<C extends DbClient>(inner: C): C {
+  const wrapped = <T>(text: string, send: (client: DbClient) => Promise<T>): Promise<T> => {
+    if (currentTx() !== undefined || transactionSettings() === undefined) return send(inner);
+    if (CONTROL.has(statementVerb(text))) return send(inner);
+    // `client: inner`, never this proxy: the BEGIN must pin a connection of the real pool. A plain
+    // read is `READ ONLY`, so it does not mark a `withReplicaReads` scope as having written.
+    return withTransaction((tx) => send(tx), { client: inner, readOnly: isPlainRead(text) });
+  };
+  const sends: DbClient = {
+    query: <T>(fragment: SqlFragment) =>
+      wrapped(fragment.text, (client) => client.query<T>(fragment)),
+    one: <T>(fragment: SqlFragment) => wrapped(fragment.text, (client) => client.one<T>(fragment)),
+    execute: (fragment: SqlFragment) =>
+      wrapped(fragment.text, (client) => client.execute(fragment)),
+  };
+  return new Proxy(inner, {
+    get(target, property, receiver) {
+      if (SENDS.has(property)) return Reflect.get(sends, property);
+      return Reflect.get(target, property, receiver);
+    },
+  });
+}

package/src/row-security-catalog.ts

@@ -0,0 +1,26 @@
+// Single responsibility: the catalog's half of a table's row security, as names — the policies on
+// each table whose row security is enabled AND forced. A policy on a table that is not forced binds
+// no owner, and one on a table that is not enabled binds nobody, so neither is held.
+
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+/** One policy on a table whose row security binds: what `introspectSchema()` reads. */
+export interface PolicyNameRow {
+  readonly table_name: string;
+  readonly policy_name: string;
+}
+
+/** Names only, as `triggerNames`: a guard is judged by being THERE, never by `pg_get_expr` text. */
+export const policyNameRows = (
+  client: DbClient,
+  schema: string,
+): Promise<readonly PolicyNameRow[]> =>
+  client.query<PolicyNameRow>(sql`
+    select c.relname as table_name, p.polname as policy_name
+    from pg_policy p
+    join pg_class c on c.oid = p.polrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and c.relrowsecurity and c.relforcerowsecurity
+    order by c.relname, p.polname
+  `);

package/src/row-security-migrator.ts

@@ -0,0 +1,48 @@
+// Single responsibility: an embedded database's migrate step, held as `x_migrator`. On PGlite the
+// one session is a superuser, so without this every table belongs to it and the default privileges
+// `x_migrator` sets for `x_app` never apply. What the superuser already owns in `public` is handed
+// over first — a table created before the flag must still be alterable by the next migration.
+
+import type { DbClient } from './client';
+import { ensureRowSecurityRoles, MIGRATOR_ROLE } from './row-security-roles';
+import { identifier, raw } from './sql';
+
+/**
+ * Every relation, type and routine in `public` the session's user owns, given to the migrator. A
+ * sequence a column owns follows its table (`alter sequence` on it is refused); an extension's
+ * member objects stay the extension's.
+ */
+export function migratorOwnershipSql(): string {
+  const migrator = identifier(MIGRATOR_ROLE).text;
+  const member = (catalog: string): string =>
+    `not exists (select from pg_depend d where d.classid = '${catalog}'::regclass and d.objid = o.oid and d.deptype in ('a', 'i', 'e'))`;
+  return (
+    'do $own$ declare r record; begin ' +
+    'for r in select o.oid::regclass as name, ' +
+    "case o.relkind when 'v' then 'view' when 'm' then 'materialized view' when 'S' then 'sequence' when 'f' then 'foreign table' else 'table' end as kind " +
+    "from pg_class o where o.relnamespace = 'public'::regnamespace and o.relkind in ('r', 'p', 'v', 'm', 'S', 'f') " +
+    `and o.relowner = (select oid from pg_roles where rolname = current_user) and ${member('pg_class')} loop ` +
+    `execute format('alter %s %s owner to ${migrator}', r.kind, r.name); end loop; ` +
+    "for r in select o.oid::regtype as name from pg_type o where o.typnamespace = 'public'::regnamespace and o.typtype in ('e', 'd', 'r', 'm') " +
+    `and o.typowner = (select oid from pg_roles where rolname = current_user) and ${member('pg_type')} loop ` +
+    `execute format('alter type %s owner to ${migrator}', r.name); end loop; ` +
+    "for r in select o.oid::regprocedure as name from pg_proc o where o.pronamespace = 'public'::regnamespace " +
+    `and o.proowner = (select oid from pg_roles where rolname = current_user) and ${member('pg_proc')} loop ` +
+    `execute format('alter routine %s owner to ${migrator}', r.name); end loop; ` +
+    'end $own$'
+  );
+}
+
+/**
+ * The roles, the hand-over, then `set role x_migrator` for the migrate step's scope. Returns the
+ * undo: `reset role`, so the session is the bootstrap user again for whatever runs next. Only on an
+ * engine whose roles are ours: an external database's migrator is the operator's `DATABASE_URL`.
+ */
+export async function holdMigratorRole(client: DbClient): Promise<() => Promise<void>> {
+  await ensureRowSecurityRoles(client);
+  await client.execute(raw(migratorOwnershipSql()));
+  await client.execute(raw(`set role ${identifier(MIGRATOR_ROLE).text}`));
+  return async () => {
+    await client.execute(raw('reset role'));
+  };
+}

package/src/row-security-plan.ts

@@ -0,0 +1,58 @@
+// Single responsibility: what `x db gen` emits when `database.rowSecurity` flips — the policy on
+// every tenant table, both directions, on the precedent of `generate-append-only.ts`. Pure over
+// its inputs: which tables declare a tenant, and which already carry a recorded policy.
+
+import type { Plan } from './foreign-key-plan';
+import { dropRowSecuritySql, enableRowSecuritySql } from './row-security';
+import { identifier } from './sql';
+
+/** A table declaring `tenant:`, its tenant column's physical name, and that column's SQL type. */
+export interface TenantTable {
+  readonly table: string;
+  readonly column: string;
+  readonly type: string;
+}
+
+export interface RowSecurityPlanInput {
+  /** `database.rowSecurity`. Off removes every recorded policy; on adds every missing one. */
+  readonly enabled: boolean;
+  readonly tenantTables: readonly TenantTable[];
+  /** Tables the latest snapshot records as carrying the policy. */
+  readonly recorded: ReadonlySet<string>;
+  /** The migrator role the app role's grants are issued from, or none (grants left to the operator). */
+  readonly appRole?: string | undefined;
+}
+
+/**
+ * Up: enable, force, policy, and the app role's grants on each table that should carry one and is
+ * not recorded; drop each recorded one that should not. Down reverses each. A table created in the
+ * same migration needs no `down` of its own — its `down` is `drop table`, and this runs after it.
+ * `x_*` tables declare no tenant and so are never here.
+ */
+export function rowSecurityPlan(plan: Plan, input: RowSecurityPlanInput): void {
+  const wanted = new Set(input.enabled ? input.tenantTables.map((entry) => entry.table) : []);
+  for (const entry of input.tenantTables) {
+    if (!wanted.has(entry.table) || input.recorded.has(entry.table)) continue;
+    plan.up.push(...enableRowSecuritySql(entry.table, entry.column, entry.type));
+    if (input.appRole !== undefined) {
+      plan.up.push(
+        `grant select, insert, update, delete on ${identifier(entry.table).text} to ${identifier(input.appRole).text};`,
+      );
+    }
+    // `down` is reversed whole, so these run drop-policy first.
+    plan.down.push(...[...dropRowSecuritySql(entry.table)].reverse());
+  }
+  for (const table of [...input.recorded].sort()) {
+    if (wanted.has(table)) continue;
+    const entry = input.tenantTables.find((candidate) => candidate.table === table);
+    plan.up.push(...dropRowSecuritySql(table));
+    if (entry !== undefined) {
+      plan.down.push(...[...enableRowSecuritySql(entry.table, entry.column, entry.type)].reverse());
+    }
+  }
+}
+
+/** What the snapshot records after this migration: the tables that carry the policy. */
+export function rowSecurityAfter(input: RowSecurityPlanInput): ReadonlySet<string> {
+  return new Set(input.enabled ? input.tenantTables.map((entry) => entry.table) : []);
+}