@ultimat3/db 29.3.2 → 29.4.0

package/src/generate.ts

@@ -7,11 +7,12 @@ import { systemClock } from '@ultimat3/core';
 import { checkClauses, checkPlan, declaredChecks } from './check-ddl';
 import { alterColumnInPlace } 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 { appendOnlyBackfillRefused, appendOnlyPlan } from './generate-append-only';
+import { assembleSteps } from './generate-steps';
 import type { Regeneration } from './generated-column';
 import { generatedClause, isGenerated, regenerate } from './generated-column';
 import { createIndex, impliedByColumnClause } from './index-ddl';
@@ -32,7 +33,7 @@ import { moveDependentsAside } from './retype-dependents';
 import { moveKeysAside, retypedColumns, retypedIn } from './retype-keys';
 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
@@ -186,6 +187,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>();
@@ -233,7 +235,7 @@ 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
@@ -283,6 +285,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 {
@@ -299,6 +313,8 @@ export function slugify(name: string): string {
 export function generateMigration(options: GenerateOptions): GeneratedMigration {
   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
@@ -334,7 +350,7 @@ 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.
     dropChangedKey(entity, live, current, plan, options.name);
-    diffTable(entity, live, plan, retypedIn(retyped, entity.table));
+    diffTable(entity, live, plan, retypedIn(retyped, entity.table), concurrent);
     const kept = new Set(entity.columns.map((column) => column.column));
     for (const column of live.columns) {
       if (kept.has(column.name)) continue;
@@ -408,19 +424,16 @@ 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 {
+  return assembleSteps({
     id,
     name: options.name,
-    fileName: `migrations/${id}.sql`,
-    up,
+    up: [...preAlters.up, ...plan.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'),
+    down: [...preAlters.down, ...plan.down].reverse(),
+    concurrent,
     snapshot: snapshotOf(options.entities, replicaIdentityFullAfter(replicaIdentity)),
-    destructive: isDestructiveMigration(up),
     unrendered,
-  };
+  });
 }

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);
   }
 }

package/src/index.ts

@@ -30,6 +30,12 @@ export type {
 export { baseClient, db, isReservable, postgresClient, setDbClient } from './client';
 export type { ColumnDefaultLike } from './column-default';
 export { defaultExpression } from './column-default';
+export {
+  concurrentIndexTarget,
+  isConcurrentIndexStatement,
+  isNonTransactional,
+  NO_TRANSACTION_MARKER,
+} from './concurrent-index';
 export { dbExecutor } from './db-executor';
 export type { DbHealthReport } from './db-health';
 export { checkDb } from './db-health';
@@ -140,6 +146,7 @@ export {
 } from './migrate';
 export {
   migrateConcurrent,
+  migrationConcurrentInTransaction,
   migrationConflict,
   migrationDestructive,
   migrationIrreversible,

package/src/marker-line.ts

@@ -0,0 +1,39 @@
+// Single responsibility: whether a migration DECLARES something with a marker line — a top-level
+// `--` comment of its own, and nothing that merely looks like one. Two markers ask this question
+// (`-- destructive: true`, `-- transaction: false`), so the scan is written once.
+
+import { noiseAt } from './sql-scan';
+
+/** Whether only spaces and tabs separate `index` from the start of its line. */
+function startsLine(sql: string, index: number): boolean {
+  for (let at = index - 1; at >= 0; at -= 1) {
+    const char = sql[at];
+    if (char === '\n') return true;
+    if (char !== ' ' && char !== '\t') return false;
+  }
+  return true;
+}
+
+/**
+ * Declared only where a reader would see it: a top-level `--` line of its own, whose WHOLE text
+ * `marker` matches.
+ *
+ * A regex over the raw file matched a marker inside `/* … *\/` and inside a dollar-quoted body,
+ * where it declares nothing and no reviewer reading the diff would call it a declaration. Scanning
+ * is what tells a comment from a comment about a comment; a marker is a lexical fact, not a
+ * substring.
+ */
+export function hasMarkerLine(sql: string, marker: RegExp): boolean {
+  let index = 0;
+  while (index < sql.length) {
+    const noise = noiseAt(sql, index);
+    if (noise === null) {
+      index += 1;
+      continue;
+    }
+    const text = sql.slice(index, noise.end);
+    if (noise.kind === 'line-comment' && startsLine(sql, index) && marker.test(text)) return true;
+    index = noise.end;
+  }
+  return false;
+}

package/src/migrate.ts

@@ -5,7 +5,6 @@
 
 import { appVersion, finiteCount, logger, renderFixShellArg } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
-import { refuseDependentViews } from './dependent-view';
 import { expectedQueryLoop } from './expected-loop';
 import { ledgerAheadOfBuild } from './migrate-rollback';
 import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
@@ -18,10 +17,9 @@ import {
   pendingMigrations,
   readLedger,
 } from './migration-ledger';
+import { applyMigrationStep } from './migration-step';
 import { poolProfileFor } from './pool-profile';
 import { raw, sql } from './sql';
-import { statementsOf } from './statement-split';
-import { withTransaction } from './transaction';
 
 export type { LedgerRow, Migration } from './migration-ledger';
 export {
@@ -175,43 +173,6 @@ async function withAdvisoryLock<T>(
   }
 }
 
-/**
- * A migration's `up` and `down` are **scripts**, and one send is one statement — because the two
- * drivers disagree about anything else. PGlite's `query()` is the extended protocol always and
- * answers `cannot insert multiple commands into a prepared statement`; `Bun.SQL.unsafe` degrades
- * to the simple protocol when no value is bound and applies the same script, which is a fact about
- * bun 1.3.14 and not a contract. `createTable` emits the table *and* every index it carries, and
- * `x dev` runs on the embedded driver, so the refusing side was the common path.
- *
- * No `expectedQueryLoop` of its own: both call sites already run inside the one declared for the
- * migration loop, and nesting here would replace that reason with a narrower one for no gain. An
- * empty script sends nothing at all, which is how a no-op migration reaches its ledger row.
- */
-async function applyScript(tx: DbClient, script: string): Promise<void> {
-  for (const statement of statementsOf(script)) await tx.execute(raw(statement));
-}
-
-/**
- * Bound how long this migration will queue behind a lock it cannot take.
- *
- * `alter table … add column` needs `ACCESS EXCLUSIVE`. A long `SELECT` holding `ACCESS SHARE`
- * makes it wait — and because Postgres' lock queue is FIFO, **every subsequent query on that table
- * queues behind the ALTER**. The `migrate` profile runs `statement_timeout = 0` deliberately, so
- * without this the migrator waits forever and the app is down on one table for as long as the
- * reporting query runs. `lock_timeout` bounds the *wait* alone and never the work, which is why it
- * is the right knob where `statement_timeout` is not.
- *
- * `SET LOCAL`, inside the migration's own transaction: it reverts at COMMIT, so a value chosen for
- * DDL never leaks onto the session the ledger insert or the next migration runs on. A 0 disables
- * it, exactly like `statementTimeoutMs`. The failure it produces is `55P03`, typed as
- * `X_DB_LOCK_TIMEOUT` by `driverError` with the `pg_stat_activity` read as its fix.
- */
-async function setLockTimeout(tx: DbClient, lockTimeoutMs: number): Promise<void> {
-  if (lockTimeoutMs <= 0) return;
-  // `SET LOCAL` takes no parameter placeholder, and the value is a validated integer of ours.
-  await tx.execute(raw(`SET LOCAL lock_timeout = ${Math.round(lockTimeoutMs)}`));
-}
-
 /**
  * `migrate` role's profile whatever role is running, because the statement is a migration whatever
  * process issues it: `x db migrate` from a laptop, `x dev`'s boot and `ROLE=migrate` all take the
@@ -271,27 +232,23 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
           const done: AppliedMigration[] = [];
           for (const migration of pending) {
             const at = performance.now();
-            await withTransaction(
-              async (tx) => {
-                await setLockTimeout(tx, lockTimeoutMs);
-                // Before the first statement, never after the failure: a view compiled against a
-                // column this script retypes is `0A000` from the server with the view named only in
-                // a DETAIL field nothing prints, surfaced as "cannot reach the database". Costs one
-                // text scan and no round trip on a migration that retypes nothing, which is nearly
-                // all of them (`dependent-view.ts`).
-                await refuseDependentViews(tx, migration.up);
-                await applyScript(tx, migration.up);
+            // Inside a transaction, or — a migration marked `-- transaction: false` — statement by
+            // statement outside one (`migration-step.ts`). Either way the ledger row is written
+            // only after the last statement succeeded, on the lock's own session.
+            await applyMigrationStep(session, {
+              id: migration.id,
+              up: migration.up,
+              script: migration.up,
+              lockTimeoutMs,
+              record: async (client) => {
                 const durationMs = Math.round(performance.now() - at);
-                await tx.execute(sql`
+                await client.execute(sql`
                 insert into ${raw(LEDGER_TABLE)} (id, name, checksum, app_version, duration_ms)
                 values (${migration.id}, ${migration.name}, ${migrationChecksum(migration)},
                         ${appVersion}, ${durationMs})
               `);
               },
-              // The lock's own session: a migration applied on another connection is not covered by
-              // the lock at all, and on `ROLE=migrate` there is no other connection to apply it on.
-              { client: session },
-            );
+            });
             done.push({
               id: migration.id,
               name: migration.name,
@@ -369,17 +326,17 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
                   'and roll back there — its down SQL exists nowhere else',
               );
             }
-            await withTransaction(
-              async (tx) => {
-                await setLockTimeout(tx, lockTimeoutMs);
-                // Both directions: a reversal retypes the same column back, and a view created
-                // since the migration applied blocks it exactly as one created before would.
-                await refuseDependentViews(tx, migration.down);
-                await applyScript(tx, migration.down);
-                await tx.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
+            // The marker on `up` governs `down` too: the reversal of a concurrent build is a
+            // concurrent drop, refused inside a transaction just the same.
+            await applyMigrationStep(session, {
+              id: migration.id,
+              up: migration.up,
+              script: migration.down,
+              lockTimeoutMs,
+              record: async (client) => {
+                await client.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
               },
-              { client: session },
-            );
+            });
             reverted.push(row.id);
           }
           return reverted;

package/src/migration-errors.ts

@@ -8,6 +8,7 @@
 import { renderFixShellArg } from '@ultimat3/core';
 import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
 import { DbError } from './errors';
+import { statementExcerpt } from './statement-excerpt';
 
 /**
  * The migration advisory lock was still held when the wait ran out. `pg_advisory_lock` blocks with
@@ -155,3 +156,23 @@ export const migrationDestructive = (
     fix: `add the line "${DESTRUCTIVE_MARKER}" to ${file}, or regenerate it: x db gen "<name>" --allow-destructive`,
     meta: { file, kind: first.kind, statements: more + 1 },
   });
+
+/**
+ * A concurrent index statement in a migration the runner would wrap in a transaction, refused
+ * BEFORE `BEGIN` — Postgres answers `25001` only after the transaction is open, in words that name
+ * neither the migration nor the marker that fixes it. `-- transaction: false` is the marker
+ * (`concurrent-index.ts`); the path is the one directory `x db gen` writes, `packages/db/migrations`.
+ * The id is FILENAME text, so it reaches the command through `renderFixShellArg`.
+ */
+export const migrationConcurrentInTransaction = (id: string, statement: string): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_CONCURRENT_IN_TRANSACTION',
+    cause:
+      `migration "${id}" runs inside a transaction and holds a statement Postgres refuses there ` +
+      `(25001): ${statementExcerpt(statement)}`,
+    // The marker is spelled out rather than spliced: it is `NO_TRANSACTION_MARKER`, and
+    // `concurrent-index.ts` imports nothing from here, but a constant in the command position is
+    // one the shell-argument screen cannot tell from caller input.
+    fix: `sed -i '1i -- transaction: false' packages/db/migrations/${renderFixShellArg(id, '<id>')}.sql   # before it is applied — or move the statement into a migration of its own`,
+    meta: { id },
+  });