@ultimat3/db 29.3.1 → 29.4.0

package/CLAUDE.md

@@ -109,19 +109,22 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   `MIGRATION_LOCK_WAIT_MS`, then `X_MIGRATE_CONCURRENT`), declared with `expectedQueryLoop`;
   `recordingClient` stubs the lock as `locked: true`.
 - **`lock_timeout` is the migration's** (`SET LOCAL` inside each migration's transaction, from the
-  `migrate` profile's 3 s).
+  `migrate` profile's 3 s). `migration-step.ts` applies a script.
+- **`-- transaction: false` runs a migration outside a transaction** (`concurrent-index.ts`, a marker
+  on `up` that governs `down`): a concurrent statement bare and unbounded, any other in its own tx; an
+  INVALID index holding a concurrent build's name is dropped first. A concurrent statement in a
+  transactional migration is `X_MIGRATION_CONCURRENT_IN_TRANSACTION`, before `BEGIN`.
 - **The advisory lock is held by one pinned session, and `migrate()`/`rollback()` run every statement
   on it.** `lock: false` reserves nothing and takes no lock; no shipped path passes it
   (`migrate-pin.test.ts`). `migrate.live.test.ts` pins concurrent and failed-midway runs.
-- **One send is one statement**: `applyScript` sends `statementsOf(script)` one at a time inside the
-  same transaction. **`statement-split.ts` is the only splitter** (a left-to-right scan; `$1` is never a
-  `$tag$`; `\` escapes only inside `E''`; comment-only chunks dropped). **`sql-scan.ts` is the one
+- **One send is one statement**: `applyScript` sends `statementsOf(script)` one at a time.
+  **`statement-split.ts` is the only splitter** (a left-to-right scan; `$1` is never a `$tag$`; `\`
+  escapes only inside `E''`; comment-only chunks dropped). **`sql-scan.ts` is the one
   lexer** (`noiseAt`, source order; a `$tag$` needs separating from the identifier before it);
   `sql-noise.ts` holds `stripSqlNoise`.
 - **`destructive.ts` decides WHAT is destructive**: only `up`, a closed list of four (`drop table`,
   `drop column`, `truncate`, `alter column … type`), decided on blanked text and reported on the
-  original; the `-- destructive: true` marker is a top-level line comment (`hasDestructiveMarker`
-  walks `sql-scan.ts`). `X_MIGRATION_DESTRUCTIVE` (ship) and `X_MIGRATION_IRREVERSIBLE` (generate) are
+  original; a marker is a top-level line comment (`marker-line.ts`). `X_MIGRATION_DESTRUCTIVE` (ship) and `X_MIGRATION_IRREVERSIBLE` (generate) are
   two questions.
 - **The ledger audit asks one question** — `auditLedger`'s `foreign` filter is `!known.has(row.id)`;
   the app version lives in the cause.
@@ -142,10 +145,11 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   refuses); absent is `btree` through one function; `snapshotOf` records `using` only when declared;
   `indexMethodSql` re-derives the literal (`X_SQL_UNSAFE` default); a unique or ordered GIN is
   `X_INVARIANT`. `introspectSchema()` reads `pg_am` (`introspect-embedded.test.ts`).
-- **`index-plan.ts` walks both directions** (declared first, removed last). `dropRecordedIndex` emits
-  `alter table … drop constraint if exists` then `drop index` for a shape a constraint could back
-  (`mayBeConstraintBacked`); four names are skipped (primary, moved aside, rebuilt, over a dropped
-  column). `index-ddl.ts` writes the statements; `index-removal.live.test.ts`.
+- **`index-plan.ts` walks both directions** (declared first, removed last); four names are skipped
+  (primary, moved aside, rebuilt, over a dropped column). **A removal and a `concurrently: true`
+  build on a live table go to the non-transactional step** (`concurrent-plan.ts`; `generate-steps.ts`
+  makes it `<id>_concurrently` or the whole migration); a shape a constraint could back
+  (`mayBeConstraintBacked`) is unhooked in the step, after its builds. Never recorded (history).
 - **An entity's INVARIANTS reach the DDL** (`invariant-ddl.ts`): a `check` is a named constraint, a
   `unique` a unique INDEX on the one `declaredIndexes` list, an `assert` nothing; `checks` is recorded
   absent-never-`[]`; the name `<table>_<name>_<check|key>` is re-derived, bounded at 63 bytes and
@@ -169,12 +173,8 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   (`retype-keys.ts`): the retype set is derived once for the whole schema (`retypedColumns`), drops go
   in `preAlters` at the top of `up`, re-adding is `foreignKeyPlan`'s, both `breaksOn` ends are needed
   (`generate-retype-key.live.test.ts`). `sql-type.ts` reads `SQL_TYPES` with `Object.hasOwn`.
-- **A generated column** (`generated-column.ts`): the clause right after the type; generated-and-
-  defaulted refused; an expression change is `set expression as (…)`; a retype has no `using`; a NOT
-  NULL add is one statement; generated → plain is `drop expression`; plain → generated rebuilds
-  (`rebuilt`) and moves dependents aside, its own type change does not. `introspectSchema` never reads
-  `generation_expression`.
-  `generate-generated-{column,rebuild}.live.test.ts`.
+- **A generated column** (`generated-column.ts`): plain → generated rebuilds (`rebuilt`); the rest of
+  its rules are in `docs/history/db.md` (2026-10-31). `generate-generated-{column,rebuild}.live.test.ts`.
 - **`REPLICA IDENTITY FULL` is a PARAMETER** (`GenerateOptions.replicaIdentityFull`, from the CLI's
   `db-generate.ts`; `replica-identity.ts`): recorded `true` or absent, as a union; last in `up`; an
   undeclared name skipped; `down` reverts it unless this migration created the table.
@@ -218,8 +218,6 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   `x_migrations` by default. **`app-relation.ts`**: `nonAppRelations(client, schema)` — extension
   ownership from `pg_depend` (`deptype = 'e'`) plus views, materialised views and foreign tables —
   merged into `excluded` unconditionally.
-- **`unexpectedTable`'s `fix:` never names `x db gen`**: `psql -c '\d "T"'`, commented with the two
-  repairs (claim it with `create table if not exists`, or drop it).
 - **`dbDrift()` lives in `drift-errors.ts`** (it needs `shellInertIdentifier`) and is the only one —
   `@ultimat3/entity`'s copy is deleted. `errors.ts` registers `DB_ERROR_TITLES` unconditionally.
 - `drift-findings.ts` holds every `DriftDifference` constructor and `DriftKind`; `drift.ts` keeps the

package/README.md

@@ -50,6 +50,7 @@ await withTransaction(async (tx) => {
 | `declaredChecks()` / `checkClauses()` / `checkPlan()` / `columnChecks()` / `columnCheckName()` / `columnNamesConstraint()` | `As of 2026-08-25`: **every** CHECK a table declares — a column's own (`enumerated()`'s value set, `tz()`'s IANA whitelist, `locale()`'s tags, money's currency pattern and scale bound) and an invariant's — on ONE list, so `createTable`, `diffTable` and `snapshotOf` agree about what exists. A column's check reached `create table` **inline and anonymous** and nothing else: the snapshot recorded none and the diff had no arm, so a value added to `enumerated()` generated no migration and a regenerated ENUM column came back as bare `text`. The name is `<table>_<column>_check` because that is the name **Postgres itself mints** for the old anonymous form — measured — so the repair lands on the constraint an already-generated database is holding; `checkPlan` emits `drop constraint if exists` before the `add` for exactly that column, because a bare add is `42710` there and a no-op everywhere else |
 | `defaultExpression()` / `ColumnDefaultLike` | `As of 2026-08-25`: a column's `default` as SQL. A DECLARED default (`{ kind: 'value', value }`) wins; `gen_random_uuid()` and `now()` stay as the inference for a description that carries only `hasDefault` |
 | `unrenderedOf()` / `unrenderedComment()` / `UnrenderedDeclaration` | `As of 2026-08-25`: what the generator could **not** write, on `GeneratedMigration.unrendered` and as a `-- UNRENDERED` block at the top of a non-empty `up`. A generator that emits less than the declaration in silence is the defect the whole file exists against, and `x verify`'s `drift` step reads a source hash — it never reads the SQL, so the loss was green. **`unrenderedOf(entities, current)` takes the recorded schema**, required and nullable: a rule declared as an `assert` reaches no SQL by design and is no loss on its own, but one whose CHECK a previous migration RECORDED is dropped by this run and reported by nothing — five in `examples/dummy`, and `@ultimat3/cli`'s `repairFix` then offered `x db gen "drop <name>"` as the repair for the loss that command performs |
+| `isNonTransactional()` / `NO_TRANSACTION_MARKER` / `isConcurrentIndexStatement()` / `concurrentIndexTarget()` | `As of 2026-10-31`: the `-- transaction: false` marker a migration carries to run outside a transaction, and the concurrent index statements that need it → [Indexes built concurrently](#indexes-built-concurrently-and-every-index-drop) |
 | `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructiveMigration()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
 | `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail |
 | `introspectSchema()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
@@ -156,6 +157,38 @@ layer 1 covers only what existed at grant time.
 | a method that moved | drop and recreate — Postgres cannot alter one in place |
 | drift | a declared GIN against a live btree is `changed-index`, and the live method is reported by the name the catalog gave it |
 
+## Indexes built concurrently, and every index drop
+
+`As of 2026-10-31`. A plain `create index` holds SHARE on the table for the whole build — every
+insert, update and delete waits — and a plain `drop index` takes ACCESS EXCLUSIVE, so reads wait
+too. `create index concurrently` / `drop index concurrently` take SHARE UPDATE EXCLUSIVE, which
+queues neither, and Postgres refuses both inside a transaction block (`25001`).
+
+```ts
+import { entity, text, uuid } from '@ultimat3/entity';
+
+entity('runs', {
+  columns: { id: uuid().primaryKey(), status: text({ max: 20 }), bank: text({ max: 40 }) },
+  indexes: [{ on: ['status'], concurrently: true }],
+});
+```
+
+| | |
+|---|---|
+| declared | `IndexDescriptionLike.concurrently` — `true` or absent. HOW the index is built, never WHAT it is: not in its name, not in the snapshot, and switching it on or off for an existing index generates nothing |
+| emitted | `create index concurrently if not exists "runs_status_idx" on "runs" ("status");`, down `drop index concurrently if exists "runs_status_idx";` |
+| removed index | **always** `drop index concurrently if exists`, whether or not it was built concurrently — down rebuilds it concurrently from the recorded definition. A total unique btree (a shape a UNIQUE constraint may back, where `drop index concurrently` is `2BP01`) is first unhooked by `alter table … drop constraint if exists` in the same step, right before its drop — never in an earlier transaction, whose rollback could not restore it |
+| moved definition | a `concurrently: true` index whose columns, predicate, order or method moved is dropped and rebuilt, both concurrently — between the two the table has neither (name the new shape differently to build it beside the old one) |
+| where it does not apply | an index on a table the same migration creates (empty, invisible until COMMIT), and one over a column a retype or a rebuild already holds ACCESS EXCLUSIVE for: both stay in the transaction |
+| the files | no concurrent work: ONE transactional migration, as before. Concurrent work only: ONE migration marked `-- transaction: false`. Both: TWO — `<id>.sql` (the transaction) and `<id>_concurrently.sql` (outside it), sorting in that order, each with its own snapshot and hash. Expand → contract: inside the step every build precedes every drop and constraint unhook, so a renamed key's replacement exists before the old key goes |
+| the runner | `migrate()` / `rollback()` run a `-- transaction: false` migration one statement at a time: a concurrent statement bare, with **no** `lock_timeout` (a concurrent build waits for every older transaction, and that wait is a lock wait); any other statement in a short transaction of its own under the migration's `lock_timeout`. The ledger row is written after the last statement |
+| an interrupted build | leaves an INVALID index holding the name. Before each named `create index concurrently`, the runner reads `pg_index.indisvalid` through `to_regclass(<name>)` and drops an invalid one concurrently first; every statement is `if [not] exists`, so a failed step is simply re-run |
+| refused | a concurrent statement in a migration WITHOUT the marker: `X_MIGRATION_CONCURRENT_IN_TRANSACTION`, before `BEGIN` |
+| destructive | never — an index holds no row. A column or table drop in the same diff is still marked |
+
+To drop an index on a hot table: delete it from the entity's `indexes`, `x db gen "drop <name>"`,
+commit what it writes, ship. The drop is its own non-transactional migration.
+
 ## Read replicas
 
 Opt in twice, and the second one is why it is safe.
@@ -455,7 +488,9 @@ and the lock — for hours, so a deploy hook sat inside one statement printing n
 `helm upgrade --wait` blocked and `backoffLimit` never fired, because a job that never finishes
 never fails. It then ensures `x_migrations`
 (`id, name, checksum, applied_at, app_version, duration_ms`), audits, then applies each pending
-migration inside its own transaction. It refuses **before applying anything** when:
+migration inside its own transaction — or, for one marked `-- transaction: false`, one
+autocommitted statement at a time ([Indexes built concurrently](#indexes-built-concurrently-and-every-index-drop)).
+It refuses **before applying anything** when:
 
 - the ledger records a migration this build does not ship **and** its `app_version` differs from
   the running one — another version owns the database; or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "29.3.1",
+  "version": "29.4.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.1"
+    "@ultimat3/core": "29.4.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/concurrent-index.ts

@@ -0,0 +1,137 @@
+// Single responsibility: what makes a migration NON-TRANSACTIONAL, and which of its statements are
+// the concurrent index builds that need it. `create index concurrently` and `drop index
+// concurrently` are refused inside a transaction block (`25001`), so the one marker line below is
+// how a migration says "run me statement by statement, outside one" — read by `migration-step.ts`.
+
+import { hasMarkerLine } from './marker-line';
+import { IDENTIFIER_CHAR, noiseAt } from './sql-scan';
+import { statementsOf } from './statement-split';
+
+/**
+ * The line a migration carries to run outside a transaction. Written into `up` by `x db gen` for
+ * the step that holds every concurrent index build, and it governs BOTH halves of the file: the
+ * `down` of a concurrent build is a concurrent drop, refused inside a transaction just the same.
+ */
+export const NO_TRANSACTION_MARKER = '-- transaction: false';
+
+/** The whole comment, as `-- destructive: true` is matched: a mention declares nothing. */
+const MARKER_COMMENT = /^--[ \t]*transaction:[ \t]*false[ \t]*\r?\n?$/i;
+
+/** Whether this migration's `up` declares it runs outside a transaction. */
+export const isNonTransactional = (up: string): boolean => hasMarkerLine(up, MARKER_COMMENT);
+
+interface Token {
+  readonly text: string;
+  /** A word to compare, lower-cased — `undefined` for a quoted identifier or a punctuation mark. */
+  readonly word: string | undefined;
+}
+
+const WHITESPACE = /\s/;
+
+/**
+ * The first `limit` tokens of one statement: comments skipped, a quoted identifier kept whole and
+ * verbatim, a literal or dollar body ending the read — no statement this file recognises has one
+ * before the name it is after. `sql-scan.ts` is the lexer, so a `"create"` is a name and not a verb.
+ */
+function leadingTokens(statement: string, limit: number): readonly Token[] {
+  const tokens: Token[] = [];
+  let index = 0;
+  while (index < statement.length && tokens.length < limit) {
+    const noise = noiseAt(statement, index);
+    if (noise !== null) {
+      if (noise.kind === 'string' || noise.kind === 'dollar-body') break;
+      if (noise.kind === 'identifier') {
+        tokens.push({ text: statement.slice(index, noise.end), word: undefined });
+      }
+      index = noise.end;
+      continue;
+    }
+    const char = statement[index] ?? '';
+    if (WHITESPACE.test(char)) {
+      index += 1;
+      continue;
+    }
+    let end = index + 1;
+    if (IDENTIFIER_CHAR.test(char)) {
+      while (end < statement.length && IDENTIFIER_CHAR.test(statement[end] ?? '')) end += 1;
+    }
+    const text = statement.slice(index, end);
+    tokens.push({ text, word: IDENTIFIER_CHAR.test(char) ? text.toLowerCase() : undefined });
+    index = end;
+  }
+  return tokens;
+}
+
+/**
+ * The index a `create [unique] index concurrently [if not exists] <name>` builds, spelled exactly
+ * as the statement spells it (`"runs_status_idx"`, `public.runs_status_idx`) — the text
+ * `to_regclass()` resolves and `drop index concurrently if exists` accepts. `null` for every other
+ * statement, and for an unnamed build: Postgres picks that name, so there is nothing to look up.
+ */
+export function concurrentIndexTarget(statement: string): string | null {
+  const tokens = leadingTokens(statement, 12);
+  const word = (at: number): string | undefined => tokens[at]?.word;
+  let at = 0;
+  if (word(at) !== 'create') return null;
+  at += word(at + 1) === 'unique' ? 2 : 1;
+  if (word(at) !== 'index' || word(at + 1) !== 'concurrently') return null;
+  at += 2;
+  if (word(at) === 'if' && word(at + 1) === 'not' && word(at + 2) === 'exists') at += 3;
+  const name = tokens[at];
+  if (name === undefined || name.word === 'on') return null;
+  const dot = tokens[at + 1];
+  const tail = tokens[at + 2];
+  if (dot?.text === '.' && tail !== undefined) return `${name.text}.${tail.text}`;
+  return name.text;
+}
+
+/**
+ * Whether one statement is an index build or drop Postgres refuses inside a transaction block:
+ * `create [unique] index concurrently`, `drop index concurrently`, `reindex … concurrently`.
+ */
+export function isConcurrentIndexStatement(statement: string): boolean {
+  const words = leadingTokens(statement, 8).map((token) => token.word);
+  const [first, second, third, fourth] = words;
+  if (first === 'create') {
+    return second === 'unique'
+      ? third === 'index' && fourth === 'concurrently'
+      : second === 'index' && third === 'concurrently';
+  }
+  if (first === 'drop') return second === 'index' && third === 'concurrently';
+  return first === 'reindex' && reindexIsConcurrent(statement);
+}
+
+/** The values that switch a boolean `REINDEX` option OFF — Postgres' own spellings of false. */
+const OFF = new Set(['false', 'off', '0', 'no']);
+
+/**
+ * `REINDEX [ ( option [, …] ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURRENTLY ] name`
+ * — read whole, never through a fixed window: the option list has no length bound, and
+ * `CONCURRENTLY [ boolean ]` may itself be one of the options.
+ */
+function reindexIsConcurrent(statement: string): boolean {
+  const tokens = leadingTokens(statement, Number.POSITIVE_INFINITY);
+  let at = 1;
+  if (tokens[at]?.text === '(') {
+    let option: (string | undefined)[] = [];
+    const settle = (): boolean => option[0] === 'concurrently' && !OFF.has(option[1] ?? '');
+    for (at += 1; at < tokens.length; at += 1) {
+      const text = tokens[at]?.text;
+      if (text === ')' || text === ',') {
+        if (settle()) return true;
+        option = [];
+        if (text === ')') break;
+        continue;
+      }
+      option.push(tokens[at]?.word);
+    }
+    at += 1;
+  }
+  // The object kind, then the modifier — never the name after it, so `index "concurrently"` and
+  // `index concurrently_idx` are not concurrent.
+  return tokens[at + 1]?.word === 'concurrently';
+}
+
+/** The first statement of `script` that cannot run inside a transaction, or `undefined`. */
+export const firstConcurrentStatement = (script: string): string | undefined =>
+  statementsOf(script).find(isConcurrentIndexStatement);

package/src/concurrent-plan.ts

@@ -0,0 +1,176 @@
+// Single responsibility: the index work `x db gen` moves OUT of the migration's transaction into a
+// step of its own — every `concurrently: true` build and every index REMOVAL, whose concurrent
+// forms queue no read and no write, and which Postgres runs only outside a transaction block.
+// `index-plan.ts` decides which; this file writes the statements and the intermediate snapshot.
+
+import type { IndexDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import {
+  asDeclared,
+  createIndex,
+  dropIndexConcurrently,
+  indexShape,
+  mayBeConstraintBacked,
+} from './index-ddl';
+import type { IndexDescription, SchemaDescription } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * One index the non-transactional step changes: `recorded` is what stood there before it (absent
+ * for a new build) — what the transactional step's snapshot still records (`intermediateSnapshot`).
+ */
+export interface DeferredIndex {
+  readonly table: string;
+  readonly name: string;
+  readonly recorded?: IndexDescription | undefined;
+}
+
+/**
+ * The non-transactional step's statements, in two phases, and what each changes for the snapshot.
+ * `up`/`down` EXPAND (every build), `contract`/`contractDown` CONTRACT (every removal): the step
+ * runs all of the first before any of the second, so a replacement exists before what it replaces
+ * goes — across tables too, since the phases are joined once, at assembly (`stepStatements`).
+ */
+export interface ConcurrentPlan extends Plan {
+  readonly contract: string[];
+  readonly contractDown: string[];
+  readonly deferred: DeferredIndex[];
+}
+
+export const emptyConcurrentPlan = (): ConcurrentPlan => ({
+  up: [],
+  down: [],
+  contract: [],
+  contractDown: [],
+  deferred: [],
+});
+
+/**
+ * The step's script in apply order — expand, then contract — and its reversal: the removed
+ * indexes are restored FIRST, then the new ones dropped, so the reversal has no gap either.
+ */
+export function stepStatements(plan: ConcurrentPlan): {
+  readonly up: readonly string[];
+  readonly down: readonly string[];
+} {
+  return {
+    up: [...plan.up, ...plan.contract],
+    down: [...plan.down, ...plan.contractDown].reverse(),
+  };
+}
+
+/** A declared index this migration builds new, concurrently, with its concurrent drop as `down`. */
+export function buildConcurrently(
+  table: string,
+  index: IndexDescriptionLike,
+  concurrent: ConcurrentPlan,
+): void {
+  concurrent.up.push(createIndex(table, index, true));
+  concurrent.down.push(dropIndexConcurrently(index.name));
+  concurrent.deferred.push({ table, name: index.name });
+}
+
+/**
+ * Drop 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 `create unique index "posts_slug_key"` and is a plain index.
+ * `snapshotOf` records both as `{ unique: true, primary: false }`.
+ *
+ * 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 [if exists] "n"`                 | **2BP01** — not suppressed | ok               |
+ * | `drop index concurrently if exists "n"`      | **2BP01** — not suppressed | ok               |
+ * | `alter table … drop constraint if exists`    | drops it, index and all    | notice, no-op    |
+ *
+ * So the shape `mayBeConstraintBacked` cannot rule out is first unhooked by the ALTER, and the
+ * concurrent drop after it is then a no-op notice or the whole job. Constraint first: reversed,
+ * the drop reaches a constraint's index and is the 2BP01 this exists to avoid.
+ *
+ * Both in the SAME non-transactional step, and in the phase `into` names. Never the ALTER in the
+ * transactional step before it: that step's `down` cannot restore a constraint, so a rollback after
+ * a failed concurrent step left the table with no uniqueness at all — and it would unhook the old
+ * key before a concurrent replacement existed, letting in the duplicates that then fail its build.
+ * The ALTER takes ACCESS EXCLUSIVE, so the runner gives a statement like it a transaction of its
+ * own under `lock_timeout` (`migration-step.ts`); the concurrent drop stays unbounded.
+ */
+function dropRecordedConcurrently(table: string, recorded: IndexDescription, into: string[]): void {
+  if (mayBeConstraintBacked(recorded)) {
+    into.push(
+      `alter table ${identifier(table).text} drop constraint if exists ${identifier(recorded.name).text};`,
+    );
+  }
+  into.push(dropIndexConcurrently(recorded.name));
+}
+
+/**
+ * A recorded index no entity declares any more: dropped concurrently, and restored by `down` —
+ * concurrently too — from what the SNAPSHOT recorded, never from the entity that stopped declaring it.
+ */
+export function removeConcurrently(
+  table: string,
+  recorded: IndexDescription,
+  concurrent: ConcurrentPlan,
+): void {
+  dropRecordedConcurrently(table, recorded, concurrent.contract);
+  concurrent.contractDown.push(createIndex(table, asDeclared(recorded), true));
+  concurrent.deferred.push({ table, name: recorded.name, recorded });
+}
+
+/**
+ * A `concurrently: true` index whose definition moved: dropped and rebuilt, both concurrently —
+ * `redefineIndex`'s pair outside the transaction. Between the two statements the table has neither
+ * definition; for a unique index that is a window with no uniqueness, the price of never blocking a
+ * write (name the new shape differently to build it beside the old one instead).
+ */
+export function redefineConcurrently(
+  table: string,
+  index: IndexDescriptionLike,
+  recorded: IndexDescription,
+  concurrent: ConcurrentPlan,
+): void {
+  if (indexShape(index) === indexShape(recorded)) return;
+  // One name, so no expand → contract is possible: the drop must precede the build, in the
+  // expand phase, in that order.
+  dropRecordedConcurrently(table, recorded, concurrent.up);
+  concurrent.up.push(createIndex(table, index, true));
+  // Pushed forwards and read backwards, as `redefineIndex`'s: the recorded definition lands last.
+  concurrent.down.push(
+    createIndex(table, asDeclared(recorded), true),
+    dropIndexConcurrently(index.name),
+  );
+  concurrent.deferred.push({ table, name: index.name, recorded });
+}
+
+/**
+ * The schema the TRANSACTIONAL step leaves behind when a non-transactional one follows it: the
+ * final snapshot with every deferred index put back the way it was — gone if it is new, its
+ * recorded definition if it is removed or rebuilt. The sidecar is "the schema this migration leaves
+ * behind", and a database that applied the first step alone holds exactly this: the first step
+ * removes no index and unhooks no constraint, so every recorded one is still there.
+ */
+export function intermediateSnapshot(
+  final: SchemaDescription,
+  deferred: readonly DeferredIndex[],
+): SchemaDescription {
+  return {
+    tables: final.tables.map((table) => {
+      const mine = deferred.filter((each) => each.table === table.name);
+      if (mine.length === 0) return table;
+      const names = new Set(mine.map((each) => each.name));
+      return {
+        ...table,
+        indexes: [
+          ...table.indexes.filter((index) => !names.has(index.name)),
+          ...mine.flatMap((each) => (each.recorded === undefined ? [] : [each.recorded])),
+        ],
+      };
+    }),
+  };
+}

package/src/destructive.ts

@@ -3,8 +3,8 @@
 // an *undeclared* drop is not. Only `up` is ever asked: reversing `create table` is `drop table`,
 // so a rail reading `down` would mark every migration ever generated, and a mark on all is none.
 
+import { hasMarkerLine } from './marker-line';
 import { stripSqlNoise } from './sql-noise';
-import { noiseAt } from './sql-scan';
 import { statementExcerpt } from './statement-excerpt';
 import { statementsOf } from './statement-split';
 
@@ -18,40 +18,12 @@ export const DESTRUCTIVE_MARKER = '-- destructive: true';
  */
 const MARKER_COMMENT = /^--[ \t]*destructive:[ \t]*true[ \t]*\r?\n?$/i;
 
-/** 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.
- *
+ * Declared only where a reader would see it: a top-level `--` line of its own (`marker-line.ts`).
  * A regex over the raw file matched the marker inside `/* … *\/` and inside a dollar-quoted body,
- * where it declares nothing and no reviewer reading the diff would call it a declaration — yet it
- * bought the file past `x verify`. Scanning is what tells a comment from a comment about a
- * comment; the marker is a lexical fact, not a substring.
+ * where it declares nothing — yet it bought the file past `x verify`.
  */
-export function hasDestructiveMarker(sql: string): 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_COMMENT.test(text)) {
-      return true;
-    }
-    index = noise.end;
-  }
-  return false;
-}
+export const hasDestructiveMarker = (sql: string): boolean => hasMarkerLine(sql, MARKER_COMMENT);
 
 export type DestructiveKind = 'drop-table' | 'drop-column' | 'retype-column' | 'truncate';
 

package/src/entity-shape.ts

@@ -97,6 +97,14 @@ export interface IndexDescriptionLike {
    * the declarer; this package cannot import it, so the method crosses the seam structurally.
    */
   readonly using?: IndexMethod | undefined;
+  /**
+   * `indexes: [{ on, concurrently: true }]`: build it with `create index concurrently` in a
+   * migration of its own that runs OUTSIDE a transaction (`concurrent-index.ts`), so a hot table
+   * keeps taking writes while it builds. HOW the index is built, never WHAT it is — so it is not
+   * part of the name, not recorded in a snapshot and never a reason to rebuild one. Absent is the
+   * plain, transactional `create index` every index was before it existed.
+   */
+  readonly concurrently?: boolean | undefined;
 }
 
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */

package/src/errors.ts

@@ -43,6 +43,7 @@ export const DB_OWNED_ERROR_CODES = [
   'X_DB_SIBLING_SCOPE_TIMEOUT',
   'X_APPEND_ONLY_TRIGGER_MISSING',
   'X_MIGRATION_APPEND_ONLY_BACKFILL',
+  'X_MIGRATION_CONCURRENT_IN_TRANSACTION',
 ] as const;
 
 /**
@@ -94,6 +95,8 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_APPEND_ONLY_TRIGGER_MISSING: 'an append-only table has lost its refusing trigger',
   X_MIGRATION_APPEND_ONLY_BACKFILL:
     'a NOT NULL column added to an append-only table needs a default',
+  X_MIGRATION_CONCURRENT_IN_TRANSACTION:
+    'a concurrent index statement is in a migration that runs inside a transaction',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails

package/src/generate-steps.ts

@@ -0,0 +1,94 @@
+// Single responsibility: turn one diff into the migration FILES it needs — one transactional step,
+// one non-transactional step, or the first followed by the second. Split from `generate.ts`, which
+// plans the statements; this file decides which step each list is and what each step records.
+
+import { NO_TRANSACTION_MARKER } from './concurrent-index';
+import { type ConcurrentPlan, intermediateSnapshot, stepStatements } from './concurrent-plan';
+import { isDestructiveMigration } from './destructive';
+import type { GeneratedMigration } from './generate';
+import type { SchemaDescription } from './introspect';
+import { type UnrenderedDeclaration, unrenderedComment } from './unrendered';
+
+export interface DiffSteps {
+  readonly id: string;
+  readonly name: string;
+  /** The transactional step's statements, in apply order. */
+  readonly up: readonly string[];
+  /** Its reversal, already in apply order. */
+  readonly down: readonly string[];
+  /** Everything that must run outside a transaction, after `up`. */
+  readonly concurrent: ConcurrentPlan;
+  /** The schema the whole diff leaves behind. */
+  readonly snapshot: SchemaDescription;
+  readonly unrendered: readonly UnrenderedDeclaration[];
+}
+
+/** One file's worth. `destructive` is read off `up` by the gate's own classifier, never assembled. */
+function migrationOf(
+  fields: Omit<GeneratedMigration, 'fileName' | 'destructive' | 'followUp'>,
+): GeneratedMigration {
+  return {
+    ...fields,
+    fileName: `migrations/${fields.id}.sql`,
+    destructive: isDestructiveMigration(fields.up),
+  };
+}
+
+/**
+ * The step files of one diff.
+ *
+ * The unrendered report sits at the TOP of the first step's `up` and never onto an empty one:
+ * `@ultimat3/cli`'s `generateAppMigration` reads an empty `up` as "nothing changed". In a
+ * non-transactional step the marker comes first — it is the header line the runner reads.
+ *
+ * Why TWO files and never one file in two halves: a migration is one ledger row. A file whose
+ * transactional half committed and whose concurrent half then failed is either recorded (and the
+ * index never built) or not (and the next run re-applies the committed half: `42P07`). Two files
+ * are two rows, and the second is idempotent by construction (`if not exists` / `if exists`, an
+ * INVALID leftover dropped first), so a failure in it is re-run, never repaired by hand.
+ */
+export function assembleSteps(diff: DiffSteps): GeneratedMigration {
+  const { id, name, snapshot, unrendered } = diff;
+  const body = diff.up.join('\n');
+  const step = stepStatements(diff.concurrent);
+  const later = step.up.join('\n');
+  const laterDown = step.down.join('\n');
+  const outside = (report: readonly UnrenderedDeclaration[]): string =>
+    `${NO_TRANSACTION_MARKER}\n${unrenderedComment(report)}${later}`;
+  if (body.length === 0 && later.length > 0) {
+    // Only index work: the non-transactional step IS the migration, under the plain id.
+    return migrationOf({
+      id,
+      name,
+      up: outside(unrendered),
+      down: laterDown,
+      snapshot,
+      unrendered,
+      transactional: false,
+    });
+  }
+  const first = migrationOf({
+    id,
+    name,
+    up: body.length === 0 ? body : unrenderedComment(unrendered) + body,
+    down: diff.down.join('\n'),
+    // What the transactional step alone leaves behind, when a second one follows it.
+    snapshot:
+      later.length === 0 ? snapshot : intermediateSnapshot(snapshot, diff.concurrent.deferred),
+    unrendered,
+    transactional: true,
+  });
+  if (later.length === 0) return first;
+  // `_concurrently` sorts right after the plain id — as a ledger id, an `.sql` and every sidecar —
+  // so expand (the transaction) always lands before contract (the concurrent drops).
+  const followUp = migrationOf({
+    id: `${id}_concurrently`,
+    name: `${name} concurrently`,
+    up: outside([]),
+    down: laterDown,
+    snapshot,
+    unrendered: [],
+    transactional: false,
+  });
+  return { ...first, followUp };
+}