@ultimat3/db 29.3.2 → 30.0.0

package/src/generate.ts

@@ -4,14 +4,19 @@
 // field. Every generated migration must be reversible; a drop that loses data refuses instead.
 
 import { systemClock } from '@ultimat3/core';
-import { checkClauses, checkPlan, declaredChecks } from './check-ddl';
-import { alterColumnInPlace } from './column-alter';
+import { checkClauses, checkPlan } from './check-ddl';
+import { alterColumnInPlace, retypeOverDefault, wantedDefault } from './column-alter';
 import { defaultExpression } from './column-default';
-import { isDestructiveMigration } from './destructive';
+import { type ConcurrentPlan, emptyConcurrentPlan } from './concurrent-plan';
 import { dropOrder } from './drop-order';
 import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
-import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
+import { type ConstraintPlans, foreignKeyPlan, type Plan } from './foreign-key-plan';
 import { appendOnlyBackfillRefused, appendOnlyPlan } from './generate-append-only';
+import { type RowSecurityOption, rowSecurityInput } from './generate-row-security';
+import { snapshotOf } from './generate-snapshot';
+import { assembleSteps } from './generate-steps';
+import { recordTriggers, triggerPlan } from './generate-triggers';
+import { splitViews, viewPlan } from './generate-view';
 import type { Regeneration } from './generated-column';
 import { generatedClause, isGenerated, regenerate } from './generated-column';
 import { createIndex, impliedByColumnClause } from './index-ddl';
@@ -27,12 +32,16 @@ import { migrationIrreversible } from './migration-errors';
 import { addChangedKey, dropChangedKey, migrationNameArg } from './primary-key';
 import type { ReplicaIdentityInput } from './replica-identity';
 import { replicaIdentityFullAfter, replicaIdentityPlan } from './replica-identity';
+import { contractsMarkerFor, recordRetired, retirePlan } from './retired';
 import type { MovedAside } from './retype-dependents';
 import { moveDependentsAside } from './retype-dependents';
 import { moveKeysAside, retypedColumns, retypedIn } from './retype-keys';
+import { columnDropNotRetired } from './rolling-errors';
+import { rowSecurityAfter, rowSecurityPlan } from './row-security-plan';
+import { withSameTenantIndexes } from './same-tenant';
 import { identifier } from './sql';
 import { sqlType } from './sql-type';
-import { type UnrenderedDeclaration, unrenderedComment, unrenderedOf } from './unrendered';
+import { type UnrenderedDeclaration, unrenderedOf } from './unrendered';
 
 function columnClause(column: ColumnDescriptionLike): string {
   // The generation clause sits directly after the type, and `generatedClause` refuses the pairs
@@ -59,67 +68,6 @@ function columnClause(column: ColumnDescriptionLike): string {
   return parts.join(' ');
 }
 
-/** No table subscribed to, which is what every caller outside `generateMigration` describes. */
-const NONE: ReadonlySet<string> = new Set();
-
-export function snapshotOf(
-  entities: readonly EntityDescriptionLike[],
-  replicaIdentityFull: ReadonlySet<string> = NONE,
-): SchemaDescription {
-  const tables = [...entities]
-    .sort((a, b) => (a.table < b.table ? -1 : 1))
-    .map((entity): TableDescription => {
-      const columns: ColumnDescription[] = [...entity.columns]
-        .sort((a, b) => (a.column < b.column ? -1 : 1))
-        .map((column, index) => ({
-          name: column.column,
-          dataType: sqlType(column.kind),
-          nullable: !column.notNull,
-          default: defaultExpression(column),
-          position: index + 1,
-          // Only when one was declared — absent stays absent, so no snapshot written before this
-          // field existed gains a key and no app's sidecar regenerates over a fact already true.
-          ...(column.generated === undefined ? {} : { generated: column.generated }),
-        }));
-      const checks = declaredChecks(entity);
-      return {
-        schema: 'public',
-        name: entity.table,
-        columns,
-        primaryKey: [...entity.primaryKey],
-        // Whole, never partly: a snapshot that recorded the name and dropped the predicate made
-        // the next generation blind to a `where` or an `order` changing, and a partial index
-        // silently kept as a total one is a constraint the entity no longer declares.
-        //
-        // `declaredIndexes`, so a `unique` invariant's index is recorded exactly like an entity's
-        // own — a statement emitted and not recorded is `42P07` on the very next `x db gen`.
-        indexes: declaredIndexes(entity).map((index) => ({
-          name: index.name,
-          columns: [...index.columns],
-          unique: index.unique,
-          primary: false,
-          where: index.where,
-          order: index.order,
-          // Only when one was declared. Writing `using: 'btree'` out for every index would rewrite
-          // every sidecar in every app on the next `x db gen` — a diff on every file for a fact
-          // that was already true, which `indexMethodOf` reads out of the absence anyway.
-          ...(index.using === undefined ? {} : { using: index.using }),
-        })),
-        foreignKeys: foreignKeysOf(entity),
-        // Absent, never `[]`, on a table declaring none: a sidecar that predates this field must
-        // read as "nothing recorded" so the next generation adds the constraints the database is
-        // genuinely missing — the rule `using` and `generated` already state one field up.
-        ...(checks.length === 0 ? {} : { checks }),
-        // The same rule once more: `true` or absent, never `false`. This is what makes the ALTER
-        // beside it a one-time statement rather than a line every `x db gen` writes again.
-        ...(replicaIdentityFull.has(entity.table) ? { replicaIdentityFull: true as const } : {}),
-        // `true` or absent once more — the record that makes the trigger a one-time statement.
-        ...(entity.appendOnly === true ? { appendOnly: true as const } : {}),
-      };
-    });
-  return { tables };
-}
-
 function createTable(entity: EntityDescriptionLike): readonly string[] {
   const clauses = entity.columns.map(columnClause);
   if (entity.primaryKey.length > 0) {
@@ -176,8 +124,8 @@ function retypeColumn(
   const alter = (type: string): string =>
     `alter table ${identifier(table).text} alter column ${identifier(column.column).text} ` +
     `type ${type} using ${identifier(column.column).text}::${type};`;
-  plan.up.push(alter(wanted));
-  plan.down.push(alter(recorded.dataType));
+  retypeOverDefault(table, column, recorded, plan, alter(wanted), alter(recorded.dataType));
+  moved.defaults.add(column.column);
   return 'altered';
 }
 
@@ -186,6 +134,7 @@ function diffTable(
   live: TableDescription,
   plan: Plan,
   retyped: ReadonlySet<string>,
+  concurrent: ConcurrentPlan,
 ): void {
   const existing = new Map(live.columns.map((column) => [column.name, column]));
   const added = new Set<string>();
@@ -193,16 +142,27 @@ function diffTable(
   // over it has to be stated again even though its own definition never moved.
   const rebuilt = new Set<string>();
   // What a retype dropped ahead of itself, read by the two arms below.
-  const moved: MovedAside = { indexes: new Set(), checks: new Set() };
+  const moved: MovedAside = { indexes: new Set(), checks: new Set(), defaults: new Set() };
   for (const column of entity.columns) {
     const recorded = existing.get(column.column);
     if (recorded !== undefined) {
       if (retypeColumn(live, column, recorded, plan, moved, retyped) === 'rebuilt') {
         rebuilt.add(column.column);
       } else {
-        // After any retype, so a new default is set against the column's new type. A rebuilt
-        // column was re-added carrying its whole clause, so it has nothing left to move.
-        alterColumnInPlace(entity, column, recorded, plan);
+        // After any retype, so nullability moves on the column's new type. A rebuilt column was
+        // re-added carrying its whole clause, so it has nothing left to move. A retype already
+        // moved the default, across the type (`column-alter.ts`).
+        alterColumnInPlace(
+          entity,
+          column,
+          moved.defaults.has(column.column)
+            ? {
+                ...recorded,
+                default: wantedDefault(column, recorded),
+              }
+            : recorded,
+          plan,
+        );
       }
       continue;
     }
@@ -233,15 +193,17 @@ function diffTable(
 
   // Both directions, in `index-plan.ts`: a recorded index the entity no longer declares is DROPPED
   // there, which is the arm this loop did not have for as long as it lived here.
-  indexPlan(entity, live, plan, { added, rebuilt, moved: moved.indexes });
+  indexPlan(entity, live, plan, { added, rebuilt, moved: moved.indexes, concurrent });
 
   // Last: a CHECK may read a column this migration just added, and `add constraint` on a column
   // that does not exist yet is `42703`. `check-ddl.ts` owns which of them move; `rebuilt` because a
   // column dropped and re-added lost its constraint while the snapshot still records it, and
   // `moved.checks` because a retype already dropped the ones written against the old type.
-  checkPlan(entity, live, plan, rebuilt, moved.checks);
+  checkPlan(entity, live, plan, rebuilt, moved.checks, concurrent);
 }
 
+export { snapshotOf } from './generate-snapshot';
+
 export interface GenerateOptions {
   readonly entities: readonly EntityDescriptionLike[];
   /** The schema migrations already declare — `expectedSchema(migrations, ledger)`. */
@@ -250,6 +212,12 @@ export interface GenerateOptions {
   readonly now?: Date | undefined;
   /** Allow a DROP COLUMN whose down cannot restore the data. `x db gen --allow-destructive`. */
   readonly allowDestructive?: boolean | undefined;
+  /**
+   * Drop a column that was never retired, for an app that stops before it starts: one instance, or
+   * `strategy: Recreate`. `x db gen --rolling-unsafe`. Consent to the outage and not to the loss,
+   * so `allowDestructive` is still asked of it.
+   */
+  readonly rollingUnsafe?: boolean | undefined;
   /**
    * Tables a live query subscribes to, so logical replication carries the old row —
    * `@ultimat3/realtime` refuses a subscription without it. Absent or empty emits nothing.
@@ -261,6 +229,12 @@ export interface GenerateOptions {
    * is the one caller that can answer it.
    */
   readonly replicaIdentityFull?: readonly string[] | undefined;
+  /**
+   * `database.rowSecurity` and each tenant table's column (`describeTenancy()`): a parameter for
+   * `replicaIdentityFull`'s reason — a config fact no entity carries. Absent is off, so a recorded
+   * policy is dropped: `@ultimat3/cli`'s `db-generate.ts` passes it on every run.
+   */
+  readonly rowSecurity?: RowSecurityOption | undefined;
 }
 
 export interface GeneratedMigration {
@@ -276,6 +250,11 @@ export interface GeneratedMigration {
    * cannot be written unmarked and then refused by `x verify` for lacking the mark.
    */
   readonly destructive: boolean;
+  /**
+   * `true` when `--rolling-unsafe` let this `up` drop a column it never retired. Absent otherwise.
+   * `x db gen` writes it as `-- rolling-unsafe: true`, the line the `drift` step's rail reads.
+   */
+  readonly rollingUnsafe?: boolean | undefined;
   /**
    * Every declaration this generator could not write down. Empty on a migration that carries the
    * whole schema, which is what makes it readable as a verdict rather than as noise — and the same
@@ -283,6 +262,18 @@ export interface GeneratedMigration {
    * (`x db gen`) and a reviewer reading the committed file are looking at one answer.
    */
   readonly unrendered: readonly UnrenderedDeclaration[];
+  /**
+   * `false` when `up` opens with `-- transaction: false` and the runner applies it statement by
+   * statement outside a transaction — the step holding every concurrent index build and every
+   * index removal (`concurrent-plan.ts`).
+   */
+  readonly transactional: boolean;
+  /**
+   * The non-transactional step this diff ALSO needs, when it needs both: `<id>_concurrently`,
+   * sorting right after this one, written as a file of its own. Absent when the diff holds only
+   * one kind — a diff that only builds or drops indexes IS the non-transactional step.
+   */
+  readonly followUp?: GeneratedMigration | undefined;
 }
 
 export function migrationStamp(now: Date): string {
@@ -296,9 +287,16 @@ export function slugify(name: string): string {
     .replace(/^_+|_+$/g, '');
 }
 
-export function generateMigration(options: GenerateOptions): GeneratedMigration {
+export function generateMigration(given: GenerateOptions): GeneratedMigration {
+  // One list for every arm below: a target's same-tenant index is declared by whoever points at it,
+  // and neither `createTable`, `diffTable` nor a snapshot may hold a different answer.
+  // Views leave here, before any table arm: none of them is a table (`generate-view.ts`).
+  const { tables, views } = splitViews(given.entities);
+  const options = { ...given, entities: withSameTenantIndexes(tables, given.current) };
   const current = options.current ?? { tables: [] };
   const plan: Plan = { up: [], down: [] };
+  // Applied AFTER `plan`, outside its transaction, in a step of its own (`concurrent-plan.ts`).
+  const concurrent = emptyConcurrentPlan();
   // Merged into `plan` once every table statement is in, never interleaved with them.
   const constraints: Plan = { up: [], down: [] };
   // Merged in BEFORE them, for the mirror-image reason: a key still pointing at a table this
@@ -320,11 +318,11 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // and the key that a retype of its column breaks is recorded on whichever table OWNS the key.
   const retyped = retypedColumns(options.entities, current);
   const predropped = moveKeysAside(current, retyped, doomed, preAlters);
-  const plans: ConstraintPlans = { constraints, preDrops, doomed, predropped };
+  const plans: ConstraintPlans = { constraints, preDrops, doomed, predropped, concurrent };
+  let droppedUnretired = false;
 
   for (const entity of options.entities) {
     const live = findTable(current, entity.table);
-    foreignKeyPlan(entity, live, plans);
     if (live === undefined) {
       plan.up.push(...createTable(entity));
       plan.down.push(`drop table ${identifier(entity.table).text};`);
@@ -333,17 +331,36 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     }
     // The key first and last, around every column statement of the table (`primary-key.ts`): the
     // snapshot below records `entity.primaryKey`, and until this arm existed nothing produced it.
+    retirePlan(entity, live, plan, options.entities);
     dropChangedKey(entity, live, current, plan, options.name);
-    diffTable(entity, live, plan, retypedIn(retyped, entity.table));
-    const kept = new Set(entity.columns.map((column) => column.column));
+    diffTable(entity, live, plan, retypedIn(retyped, entity.table), concurrent);
+    const kept = new Set([
+      ...entity.columns.map((column) => column.column),
+      ...(entity.retired ?? []),
+    ]);
     for (const column of live.columns) {
       if (kept.has(column.name)) continue;
+      // Order matters: the release boundary first, with the flag or without it. Retiring is what
+      // earns the next question; it is never consent to losing the rows, so that one still stands.
+      if (column.retired !== true && options.rollingUnsafe !== true) {
+        throw columnDropNotRetired(
+          entity.name,
+          entity.table,
+          column.name,
+          migrationNameArg(options.name),
+        );
+      }
       if (options.allowDestructive !== true) {
         throw migrationIrreversible(
           `dropping "${entity.table}"."${column.name}" discards its rows and cannot be undone`,
-          `x db gen ${migrationNameArg(options.name)} --allow-destructive   # or keep the column and deprecate it`,
+          `x db gen ${migrationNameArg(options.name)} --allow-destructive   # or put "${column.name}" back in columns and keep it`,
         );
       }
+      if (column.retired === true) {
+        plan.up.push(contractsMarkerFor(entity.table, column.name));
+      } else {
+        droppedUnretired = true;
+      }
       plan.up.push(
         `alter table ${identifier(entity.table).text} drop column ${identifier(column.name).text};`,
       );
@@ -356,6 +373,11 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     addChangedKey(entity, live, plan, options.name);
   }
 
+  // After every table's diff, so the deferred step already says which target indexes it builds.
+  for (const entity of options.entities) {
+    foreignKeyPlan(entity, findTable(current, entity.table), plans);
+  }
+
   const order = dropOrder(current.tables.filter((table) => !wanted.has(table.name)));
   for (const table of order.tables) {
     if (options.allowDestructive !== true) {
@@ -381,6 +403,11 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
 
   // After every table exists, so a `create table` in this same migration is already above it.
   appendOnlyPlan(plan, options.entities, current, created);
+  // History, its guard and counters, the same way: after every table they name exists.
+  triggerPlan(plan, options.entities, current);
+  // Then each tenant table's policy, both directions (`row-security-plan.ts`), on tables that exist.
+  const rowSecurity = rowSecurityInput(options.entities, current, options.rowSecurity);
+  rowSecurityPlan(plan, rowSecurity);
 
   // Dead last in `up`, and it is the only placement that is right for every arm: the table has to
   // exist, and a `create table` in this same migration is the reason it might not. It is ordered
@@ -408,19 +435,31 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // `current`, not the entities alone: an `assert` whose CHECK a previous migration recorded is a
   // loss only because THIS plan drops it, and the recorded schema is the only thing that knows.
   const unrendered = unrenderedOf(options.entities, current);
-  const body = [...preAlters.up, ...plan.up].join('\n');
-  const up = body.length === 0 ? body : unrenderedComment(unrendered) + body;
-  return {
+  // Dropped ahead of every table statement and created after the last one: a view compiled against
+  // a column this migration retypes or drops is `0A000`/`2BP01` otherwise.
+  const viewed = viewPlan(views, current, [...preAlters.up, ...plan.up]);
+  return assembleSteps({
     id,
     name: options.name,
-    fileName: `migrations/${id}.sql`,
-    up,
+    up: [...viewed.before.up, ...preAlters.up, ...plan.up, ...viewed.after.up],
     // Reverse order: the last thing created is the first thing dropped. `preAlters` goes in at the
     // FRONT here precisely so reversal puts it last — a key is added back only once both of its
     // ends have been retyped back, which is every other statement in the script.
-    down: [...preAlters.down, ...plan.down].reverse().join('\n'),
-    snapshot: snapshotOf(options.entities, replicaIdentityFullAfter(replicaIdentity)),
-    destructive: isDestructiveMigration(up),
+    down: [...viewed.before.down, ...preAlters.down, ...plan.down, ...viewed.after.down].reverse(),
+    concurrent,
+    snapshot: recordTriggers(
+      recordRetired(
+        snapshotOf(
+          [...options.entities, ...views],
+          replicaIdentityFullAfter(replicaIdentity),
+          rowSecurityAfter(rowSecurity),
+        ),
+        options.entities,
+        current,
+      ),
+      options.entities,
+    ),
     unrendered,
-  };
+    ...(droppedUnretired ? { rollingUnsafe: true } : {}),
+  });
 }

package/src/index-ddl.ts

@@ -83,8 +83,17 @@ function indexPredicateSql(index: IndexDescriptionLike): string {
  * Every part of the declaration reaches the statement: the whole column list in its declared
  * order, the direction when one was asked for, and the predicate that makes it partial. A part
  * dropped here is a constraint the database does not hold or an index the planner cannot use.
+ *
+ * `concurrently` writes `create index concurrently if not exists` — the spelling the
+ * non-transactional step needs (`concurrent-index.ts`): re-running a step that failed after this
+ * build finished must find it and move on, and one that failed DURING it left an INVALID index the
+ * runner drops first (`migration-step.ts`). Off, the statement is byte-for-byte what shipped before.
  */
-export function createIndex(table: string, index: IndexDescriptionLike): string {
+export function createIndex(
+  table: string,
+  index: IndexDescriptionLike,
+  concurrently = false,
+): string {
   assert(
     index.columns.length > 0,
     `index "${index.name}" on "${table}" names no columns`,
@@ -106,7 +115,9 @@ export function createIndex(table: string, index: IndexDescriptionLike): string
     `index "${index.name}" on "${table}" is ${method} and ${index.order}; only a btree orders its keys`,
     `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop order, or drop using`,
   );
-  const kind = index.unique ? 'create unique index' : 'create index';
+  const kind =
+    (index.unique ? 'create unique index' : 'create index') +
+    (concurrently ? ' concurrently if not exists' : '');
   const direction = indexOrderSql(index);
   const columns = index.columns
     .map((column) => `${identifier(column).text}${direction}`)
@@ -124,6 +135,15 @@ export function createIndex(table: string, index: IndexDescriptionLike): string
 /** `drop index "n";` — the one spelling, so a drop and its recreate cannot name it differently. */
 export const dropIndex = (name: string): string => `drop index ${identifier(name).text};`;
 
+/**
+ * `drop index concurrently if exists "n";` — the non-transactional drop. `if exists` because a
+ * re-run of a step that already dropped it must move on, and because it also removes an INVALID
+ * index a failed concurrent build left behind. Postgres refuses it on a constraint's index (2BP01),
+ * so a recorded index that may be one is unhooked first by `dropRecordedConcurrently`.
+ */
+export const dropIndexConcurrently = (name: string): string =>
+  `drop index concurrently if exists ${identifier(name).text};`;
+
 /**
  * Whether Postgres could be backing this RECORDED index with a UNIQUE constraint rather than
  * holding it as an index of its own — which decides the only question `dropIndex` cannot answer.
@@ -131,7 +151,7 @@ export const dropIndex = (name: string): string => `drop index ${identifier(name
  * A UNIQUE constraint's index is unique, total, unordered and btree; `add constraint … unique`
  * and a `unique` column clause can produce nothing else. So an index missing any one of those is
  * provably an index, and `drop index` on it is right. Everything else is genuinely ambiguous —
- * see `dropRecordedIndex`.
+ * see `dropRecordedConcurrently` (`concurrent-plan.ts`).
  */
 export function mayBeConstraintBacked(index: IndexDescription): boolean {
   return (
@@ -143,38 +163,6 @@ export function mayBeConstraintBacked(index: IndexDescription): boolean {
   );
 }
 
-/**
- * Remove a RECORDED index whose kind this generator cannot know, in statements that are correct
- * on both databases it cannot tell apart.
- *
- * `TableDescription` carries no discriminator, and it cannot be given one that would help: the
- * SAME declaration reaches the server as a CONSTRAINT or as an INDEX depending on which migration
- * created it. A `unique` column on a table `createTable` writes emits `create table … slug text
- * unique`, and Postgres backs that with a constraint named `posts_slug_key`; the same column
- * gaining `unique` later takes `diffTable`'s `create unique index "posts_slug_key"` and is a plain
- * index. `snapshotOf` records both as `{ unique: true, primary: false }`, and every sidecar already
- * on disk was written that way — a new field could not classify one of them retroactively.
- *
- * Measured on 18.4 (`index-removal.live.test.ts`), which is why the pair and not a guess:
- *
- * | statement                                  | on a constraint's index | on a plain index |
- * |--------------------------------------------|-------------------------|------------------|
- * | `drop index "n"`                           | **2BP01**               | ok               |
- * | `drop index if exists "n"`                 | **2BP01** — not suppressed | ok            |
- * | `alter table … drop constraint if exists`  | drops it, index and all | notice, no-op    |
- *
- * Constraint first, then the index: reversed, the `drop index` reaches a constraint's index and is
- * the 2BP01 this exists to avoid. Both halves carry `if exists`, so whichever one did nothing says
- * so with a notice rather than 42704.
- */
-export function dropRecordedIndex(table: string, index: IndexDescription): readonly string[] {
-  if (!mayBeConstraintBacked(index)) return [dropIndex(index.name)];
-  return [
-    `alter table ${identifier(table).text} drop constraint if exists ${identifier(index.name).text};`,
-    `drop index if exists ${identifier(index.name).text};`,
-  ];
-}
-
 /**
  * A RECORDED index as a declaration this generator can emit again — `declaredMethod`, never a
  * cast: the recorded side is typed open because the catalog shares the shape, and a method this

package/src/index-plan.ts

@@ -16,16 +16,15 @@
 // declaration is already broken — the key has nothing to point at — and the failure arrives with
 // the server's own words naming both ends.
 
+import {
+  buildConcurrently,
+  type ConcurrentPlan,
+  redefineConcurrently,
+  removeConcurrently,
+} from './concurrent-plan';
 import type { EntityDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
-import {
-  asDeclared,
-  createIndex,
-  dropIndex,
-  dropRecordedIndex,
-  impliedByColumnClause,
-  redefineIndex,
-} from './index-ddl';
+import { createIndex, dropIndex, impliedByColumnClause, redefineIndex } from './index-ddl';
 import type { TableDescription } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
 
@@ -40,6 +39,11 @@ export interface IndexPlanContext {
   readonly rebuilt: ReadonlySet<string>;
   /** Indexes a retype already dropped ahead of its ALTER (`moveDependentsAside`). */
   readonly moved: ReadonlySet<string>;
+  /**
+   * The non-transactional step (`concurrent-plan.ts`): every `concurrently: true` build and every
+   * removal lands here, outside the transaction `plan` is applied in.
+   */
+  readonly concurrent: ConcurrentPlan;
 }
 
 /**
@@ -68,19 +72,31 @@ export function indexPlan(
     // `redefineIndex` sees a definition that never moved and would emit nothing at all.
     const gone =
       context.moved.has(index.name) || index.columns.some((each) => context.rebuilt.has(each));
+    // `concurrently` only where the table is live and the index is the only thing moving: a
+    // rebuilt or retyped column already holds ACCESS EXCLUSIVE inside the transaction, so a
+    // concurrent rebuild after it buys nothing and leaves the table without the index between.
+    const concurrently = index.concurrently === true && !gone;
     if (recorded !== undefined && !gone) {
-      redefineIndex(entity.table, index, recorded, plan);
+      if (concurrently) {
+        redefineConcurrently(entity.table, index, recorded, context.concurrent);
+      } else {
+        redefineIndex(entity.table, index, recorded, plan);
+      }
       continue;
     }
     // `added` only: an index over a column that was already there is implied by no clause this
     // migration emits, so it still needs a statement of its own.
     if (impliedByColumnClause(entity, index, context.added)) continue;
+    if (concurrently) {
+      buildConcurrently(entity.table, index, context.concurrent);
+      continue;
+    }
     plan.up.push(createIndex(entity.table, index));
     // The plain drop, always: this migration CREATED it, with `create index`, so it is an index
-    // and never a constraint's — `dropRecordedIndex`'s ambiguity is about the recorded side only.
+    // and never a constraint's — the ambiguity is about the recorded side only.
     plan.down.push(dropIndex(index.name));
   }
-  removeUndeclared(entity, live, plan, context, declared);
+  removeUndeclared(entity, live, context, declared);
 }
 
 /**
@@ -88,6 +104,13 @@ export function indexPlan(
  * the SNAPSHOT recorded, never from what the entity declares, since the entity is precisely what
  * stopped describing it. The rule the retype path already states.
  *
+ * ALWAYS concurrently, in the non-transactional step (`removeConcurrently`), whether or not the
+ * index was built that way: a plain `drop index` takes ACCESS EXCLUSIVE on the TABLE, so every
+ * read and write of a hot table queued behind it. Expand → contract: the drop — and the
+ * constraint unhook a UNIQUE shape needs — lands in the step's CONTRACT phase, after everything the
+ * transactional step and the step's own builds added, so a renamed index exists twice for a moment
+ * and never zero times. Nothing records how an index was built, so the drop cannot depend on it.
+ *
  * Four names are skipped, and each one is a statement Postgres would refuse or repeat:
  *
  * | skipped                                  | because |
@@ -103,7 +126,6 @@ export function indexPlan(
 function removeUndeclared(
   entity: EntityDescriptionLike,
   live: TableDescription,
-  plan: Plan,
   context: IndexPlanContext,
   declared: ReadonlySet<string>,
 ): void {
@@ -113,7 +135,6 @@ function removeUndeclared(
     if (context.moved.has(recorded.name)) continue;
     if (recorded.columns.some((column) => context.rebuilt.has(column))) continue;
     if (!recorded.columns.every((column) => columns.has(column))) continue;
-    plan.up.push(...dropRecordedIndex(live.name, recorded));
-    plan.down.push(createIndex(live.name, asDeclared(recorded)));
+    removeConcurrently(live.name, recorded, context.concurrent);
   }
 }