@crombolo/data 0.11.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/data",
-  "version": "0.11.0",
+  "version": "0.13.1",
   "description": "SQLite and Postgres storage for crombolo: schema, migrations and repositories.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,6 +28,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.11.0"
+    "@crombolo/core": "0.13.1"
   }
 }

package/src/ambient.ts

@@ -0,0 +1,20 @@
+/** The transaction the current async chain is inside, shared by the drivers and the lock managers. */
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/** Cleared when its transaction ends, so work left running afterwards falls back to the pool. */
+export interface AmbientTransaction<T> {
+  owner: object
+  tx: T | undefined
+}
+
+export const ambient = new AsyncLocalStorage<AmbientTransaction<unknown>>()
+
+/** The open transaction this chain holds on `owner`'s connection, if any. */
+export function ambientFor<T>(owner: object): T | undefined {
+  const store = ambient.getStore()
+  return store?.owner === owner ? (store.tx as T | undefined) : undefined
+}
+
+export function insideTransaction(): boolean {
+  return ambient.getStore()?.tx !== undefined
+}

package/src/busy.ts

@@ -0,0 +1,74 @@
+/** Lock contention: recognising it in driver errors, retrying it, and the error an editor sees. */
+
+export type Contention = 'deadlock' | 'lockTimeout' | 'busy'
+
+/** A write gave up waiting for another to finish. Answered as 503 with Retry-After. */
+export class ContentBusyError extends Error {
+  constructor(
+    readonly contention: Contention,
+    readonly retryAfterSeconds = 2,
+  ) {
+    super('Someone else is changing this content right now. Try again in a moment.')
+  }
+}
+
+const POSTGRES_CODES: Record<string, Contention> = {
+  '40P01': 'deadlock',
+  '40001': 'deadlock',
+  '55P03': 'lockTimeout',
+}
+
+/** Which kind of contention a driver error reports, if any. */
+export function classifyContention(error: unknown): Contention | undefined {
+  if (error instanceof ContentBusyError) return error.contention
+  if (!error || typeof error !== 'object') return undefined
+  const { code, errno, message } = error as { code?: unknown; errno?: unknown; message?: unknown }
+  // Bun's Postgres driver reports the SQLSTATE as `errno`, other drivers as `code`.
+  for (const state of [errno, code])
+    if (typeof state === 'string' && POSTGRES_CODES[state]) return POSTGRES_CODES[state]
+  if (
+    typeof code === 'string' &&
+    (code.startsWith('SQLITE_BUSY') || code.startsWith('SQLITE_LOCKED'))
+  )
+    return 'busy'
+  if (errno === 5 || errno === 6) return 'busy'
+  if (typeof message === 'string' && /database (table )?is locked/i.test(message)) return 'busy'
+  return undefined
+}
+
+export interface RetryPolicy {
+  /** Attempts in all, the first included. */
+  attempts: number
+  /** Waits between attempts; injected so a test does not sleep. */
+  sleep: (ms: number) => Promise<void>
+  backoffMs: number
+}
+
+export const DEFAULT_RETRY: RetryPolicy = {
+  attempts: 2,
+  sleep: (ms) => Bun.sleep(ms),
+  backoffMs: 50,
+}
+
+/**
+ * Runs `fn`, retrying a deadlock: the database rolled the transaction back, so
+ * running it again is safe. A lock timeout is not retried, since the wait has
+ * already been spent. Contention that outlasts the policy becomes ContentBusyError.
+ */
+export async function retryContention<T>(
+  fn: () => Promise<T>,
+  policy: RetryPolicy = DEFAULT_RETRY,
+): Promise<T> {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      const contention = classifyContention(error)
+      if (!contention) throw error
+      if (contention !== 'deadlock' || attempt >= policy.attempts) {
+        throw error instanceof ContentBusyError ? error : new ContentBusyError(contention)
+      }
+      await policy.sleep(policy.backoffMs * attempt)
+    }
+  }
+}

package/src/change-report.ts

@@ -23,6 +23,12 @@ export interface Finding {
   subjectType:
     | 'document'
     | 'document-type'
+    | 'media-type'
+    | 'member-type'
+    | 'member'
+    | 'member-group'
+    | 'user'
+    | 'user-group'
     | 'property'
     | 'migration'
     | 'file'

package/src/cluster.ts

@@ -20,6 +20,9 @@ export interface CacheInstruction {
   createdBy: string | null
 }
 
+/** Where Postgres says an instruction was written, so nodes poll now rather than on their timer. */
+export const CACHE_INSTRUCTION_CHANNEL = 'crombolo_cache_instruction'
+
 export async function appendCacheInstruction(
   db: Db,
   instruction: { kind: CacheInstructionKind; payload?: Record<string, unknown>; by?: string },
@@ -33,6 +36,9 @@ export async function appendCacheInstruction(
       instruction.by ?? null,
     ],
   )
+  // Delivered at commit, so a write that rolls back wakes nobody.
+  if (db.dialect.name === 'postgres')
+    await db.exec('SELECT pg_notify(?, ?)', [CACHE_INSTRUCTION_CHANNEL, instruction.kind])
 }
 
 /** The highest instruction id, so a fresh node ignores history. */
@@ -60,25 +66,28 @@ export interface ServerIdentity {
   revision: string
   /** `all`, `api` or `web`: what this node serves, so the cluster can be read back by role. */
   role?: string
+  /** The Crombolo release this node runs; `version` is the schema set's. */
+  cromboloVersion?: string
 }
 
 /** Records this node in `server`; called at boot and on each poll. */
 export async function touchServer(db: Db, identity: ServerIdentity): Promise<void> {
   const now = DbDate.toDb(new Date())
   const role = identity.role ?? null
+  const crombolo = identity.cromboloVersion ?? null
   const existing = await db.query<{ node_id: string }>(
     'SELECT node_id FROM server WHERE node_id = ?',
     [identity.nodeId],
   )
   if (existing[0]) {
     await db.exec(
-      'UPDATE server SET version = ?, revision = ?, role = ?, last_seen = ? WHERE node_id = ?',
-      [identity.version, identity.revision, role, now, identity.nodeId],
+      'UPDATE server SET version = ?, revision = ?, role = ?, crombolo_version = ?, last_seen = ? WHERE node_id = ?',
+      [identity.version, identity.revision, role, crombolo, now, identity.nodeId],
     )
   } else {
     await db.exec(
-      'INSERT INTO server (node_id, version, revision, role, last_seen) VALUES (?, ?, ?, ?, ?)',
-      [identity.nodeId, identity.version, identity.revision, role, now],
+      'INSERT INTO server (node_id, version, revision, role, crombolo_version, last_seen) VALUES (?, ?, ?, ?, ?, ?)',
+      [identity.nodeId, identity.version, identity.revision, role, crombolo, now],
     )
   }
 }
@@ -89,13 +98,15 @@ export interface LiveNode {
   role: string | null
   version: string | null
   revision: string | null
+  /** Null for a row written before node releases were recorded. */
+  cromboloVersion: string | null
   lastSeen: Date
 }
 
 /** The nodes that have polled within `seenWithinMs`: the cluster as it stands. */
 export async function liveNodes(db: Db, options: { seenWithinMs: number }): Promise<LiveNode[]> {
   const rows = await db.query(
-    'SELECT node_id, role, version, revision, last_seen FROM server WHERE last_seen >= ? ORDER BY node_id',
+    'SELECT node_id, role, version, revision, crombolo_version, last_seen FROM server WHERE last_seen >= ? ORDER BY node_id',
     [DbDate.toDb(new Date(Date.now() - options.seenWithinMs))],
   )
   return rows.map((row) => ({
@@ -103,6 +114,7 @@ export async function liveNodes(db: Db, options: { seenWithinMs: number }): Prom
     role: (row.role as string | null) ?? null,
     version: (row.version as string | null) ?? null,
     revision: (row.revision as string | null) ?? null,
+    cromboloVersion: (row.crombolo_version as string | null) ?? null,
     lastSeen: DbDate.fromDb(row.last_seen) as Date,
   }))
 }

package/src/database.ts

@@ -1,9 +1,9 @@
 /** Driver-agnostic database handle. */
 
 import { Database as BunSqlite } from 'bun:sqlite'
-import { AsyncLocalStorage } from 'node:async_hooks'
+import { ambient, ambientFor } from './ambient.ts'
 import { type Dialect, type DialectName, dialectFor } from './dialect.ts'
-import { createLockManager, type LockManager } from './locks.ts'
+import { createLockManager, DEFAULT_LOCK_TIMEOUT_MS, type LockManager } from './locks.ts'
 
 export interface Db {
   readonly dialect: Dialect
@@ -12,6 +12,8 @@ export interface Db {
   exec(sql: string, params?: unknown[]): Promise<void>
   transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T>
   close(): Promise<void>
+  /** Postgres only: calls `onNotify` for each `NOTIFY` on `channel`; resolves to the way to stop. */
+  listen?(channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>
 }
 
 export interface ConnectOptions {
@@ -22,10 +24,15 @@ export interface ConnectOptions {
   file?: string
   /** Postgres connection string. Ignored for SQLite. */
   url?: string
+  /** How long a write waits for a content lock; defaults to `CROMBOLO_LOCK_TIMEOUT_SECONDS`, else 15s. */
+  lockTimeoutMs?: number
 }
 
-/** The connection the current async chain holds a transaction on. */
-const transacting = new AsyncLocalStorage<BunSqlite>()
+export function resolveLockTimeoutMs(options: ConnectOptions = {}): number {
+  if (options.lockTimeoutMs !== undefined) return options.lockTimeoutMs
+  const seconds = Number(Bun.env.CROMBOLO_LOCK_TIMEOUT_SECONDS)
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : DEFAULT_LOCK_TIMEOUT_MS
+}
 
 /**
  * One connection has one transaction at a time, but async chains interleave:
@@ -45,9 +52,10 @@ class SqliteDb implements Db {
     locks?: LockManager,
     inTransaction = false,
     gate: { tail: Promise<void> } = { tail: Promise.resolve() },
+    lockTimeoutMs?: number,
   ) {
     this.#db = db
-    this.locks = locks ?? createLockManager(this)
+    this.locks = locks ?? createLockManager(this, { timeoutMs: lockTimeoutMs })
     this.#inTransaction = inTransaction
     this.#gate = gate
   }
@@ -63,7 +71,7 @@ class SqliteDb implements Db {
   async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
     if (this.#inTransaction) return fn(this)
     const tx = new SqliteDb(this.#db, this.locks, true, this.#gate)
-    if (transacting.getStore() === this.#db) return fn(tx)
+    if (ambientFor(this.#db)) return fn(tx)
     const previous = this.#gate.tail
     let release!: () => void
     this.#gate.tail = new Promise<void>((resolve) => {
@@ -72,13 +80,16 @@ class SqliteDb implements Db {
     await previous
     try {
       this.#db.exec('BEGIN')
+      const store = { owner: this.#db, tx: tx as unknown }
       try {
-        const result = await transacting.run(this.#db, () => fn(tx))
+        const result = await ambient.run(store, () => fn(tx))
         this.#db.exec('COMMIT')
         return result
       } catch (error) {
         this.#db.exec('ROLLBACK')
         throw error
+      } finally {
+        store.tx = undefined
       }
     } finally {
       release()
@@ -94,6 +105,10 @@ interface SqlTag {
   unsafe(sql: string, params?: unknown[]): Promise<unknown>
   begin<T>(fn: (tx: SqlTag) => Promise<T>): Promise<T>
   close(): Promise<void>
+  listen(
+    channel: string,
+    onNotify: (payload: string) => void,
+  ): Promise<{ unlisten(): Promise<void> }>
 }
 
 class PostgresDb implements Db {
@@ -102,9 +117,9 @@ class PostgresDb implements Db {
   #sql: SqlTag
   #inTransaction: boolean
 
-  constructor(sql: SqlTag, locks?: LockManager, inTransaction = false) {
+  constructor(sql: SqlTag, locks?: LockManager, inTransaction = false, lockTimeoutMs?: number) {
     this.#sql = sql
-    this.locks = locks ?? createLockManager(this)
+    this.locks = locks ?? createLockManager(this, { timeoutMs: lockTimeoutMs })
     this.#inTransaction = inTransaction
   }
 
@@ -116,15 +131,33 @@ class PostgresDb implements Db {
     await this.#sql.unsafe(this.dialect.render(sql), params)
   }
 
-  /** Nested calls join the enclosing transaction, as they do on SQLite. */
+  /**
+   * Nested calls join the enclosing transaction, as they do on SQLite. The
+   * chain is marked as inside one, so a deadlock is not retried into a
+   * transaction Postgres has already aborted.
+   */
   async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
     if (this.#inTransaction) return fn(this)
-    return this.#sql.begin(async (tx) => fn(new PostgresDb(tx, this.locks, true)))
+    return this.#sql.begin(async (sql) => {
+      const tx = new PostgresDb(sql, this.locks, true)
+      const store = { owner: this, tx: tx as unknown }
+      try {
+        return await ambient.run(store, () => fn(tx))
+      } finally {
+        store.tx = undefined
+      }
+    })
   }
 
   async close(): Promise<void> {
     await this.#sql.close()
   }
+
+  async listen(channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>> {
+    if (this.#inTransaction) throw new Error('A transaction cannot listen.')
+    const subscription = await this.#sql.listen(channel, onNotify)
+    return () => subscription.unlisten()
+  }
 }
 
 export function resolveDialectName(options: ConnectOptions = {}): DialectName {
@@ -139,7 +172,7 @@ export async function connect(options: ConnectOptions = {}): Promise<Db> {
     // A modest pool: many short-lived connections exhaust Postgres' client limit,
     // and a single process does not need more.
     const sql = new SQL({ url, max: options.poolSize ?? 5 }) as unknown as SqlTag
-    const db = new PostgresDb(sql)
+    const db = new PostgresDb(sql, undefined, false, resolveLockTimeoutMs(options))
     await db.exec('CREATE EXTENSION IF NOT EXISTS citext')
     return db
   }
@@ -147,5 +180,5 @@ export async function connect(options: ConnectOptions = {}): Promise<Db> {
   sqlite.exec('PRAGMA journal_mode = WAL')
   sqlite.exec('PRAGMA foreign_keys = ON')
   sqlite.exec('PRAGMA busy_timeout = 5000')
-  return new SqliteDb(sqlite)
+  return new SqliteDb(sqlite, undefined, false, undefined, resolveLockTimeoutMs(options))
 }

package/src/index.ts

@@ -1,5 +1,7 @@
+export { insideTransaction } from './ambient.ts'
 export * from './audit.ts'
 export * from './bundle-tables/index.ts'
+export * from './busy.ts'
 export * from './change-report.ts'
 export * from './cluster.ts'
 export * from './database.ts'
@@ -9,12 +11,16 @@ export * from './maintenance.ts'
 export * from './migrations.ts'
 export * from './node-ref.ts'
 export * from './pending.ts'
+export * from './relations.ts'
+export * from './repositories/approvals.ts'
 export * from './repositories/bundles.ts'
 export * from './repositories/content-types.ts'
 export * from './repositories/data-types.ts'
+export * from './repositories/delivery-member-tokens.ts'
 export * from './repositories/dictionary.ts'
 export * from './repositories/documents.ts'
 export * from './repositories/domains.ts'
+export * from './repositories/dynamic-roots.ts'
 export * from './repositories/folders.ts'
 export * from './repositories/form-entries.ts'
 export * from './repositories/form-workflows.ts'
@@ -28,9 +34,12 @@ export * from './repositories/redirects.ts'
 export * from './repositories/references.ts'
 export * from './repositories/tags.ts'
 export * from './repositories/templates.ts'
+export * from './repositories/transfer-answers.ts'
 export * from './repositories/transfer-runs.ts'
 export * from './repositories/user-data.ts'
 export * from './repositories/users.ts'
+export * from './repositories/webhooks.ts'
+export * from './schema/approvals.ts'
 export * from './schema/assistant.ts'
 export * from './schema/audit-log.ts'
 export * from './schema/built-in-content-types.ts'
@@ -43,6 +52,8 @@ export * from './schema/client-id-prefix.ts'
 export * from './schema/content.ts'
 export * from './schema/content-seed.ts'
 export * from './schema/created-packages.ts'
+export * from './schema/delivery-member-tokens.ts'
+export * from './schema/diagnostics.ts'
 export * from './schema/elements.ts'
 export * from './schema/form-permission-prefix.ts'
 export * from './schema/group-permissions.ts'
@@ -58,12 +69,18 @@ export * from './schema/rich-text-ui.ts'
 export * from './schema/search-index.ts'
 export * from './schema/seed.ts'
 export * from './schema/since-version.ts'
+export * from './schema/transfer-answers.ts'
 export * from './schema/transfer-run-package.ts'
 export * from './schema/transfer-runs.ts'
 export * from './schema/upgrade-report.ts'
 export * from './schema/users-localisation.ts'
 export * from './schema/values.ts'
+export * from './schema/webhooks.ts'
 export * from './schema-ops.ts'
 export * from './schema-state.ts'
 export * from './search.ts'
 export * from './search-text.ts'
+export * from './setup.ts'
+export * from './tree-invariants.ts'
+export * from './url-options.ts'
+export * from './workflow-store.ts'

package/src/locks.ts

@@ -4,8 +4,12 @@
  * and necessary, while Postgres uses advisory locks.
  */
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { insideTransaction } from './ambient.ts'
+import { ContentBusyError, DEFAULT_RETRY, type RetryPolicy, retryContention } from './busy.ts'
 import type { Db } from './database.ts'
 
+export const DEFAULT_LOCK_TIMEOUT_MS = 15_000
+
 /** Mirrors Umbraco's Constants.Locks. */
 export const Locks = {
   Servers: -331,
@@ -55,49 +59,114 @@ async function reentrant<T>(
   })
 }
 
-class SqliteLockManager implements LockManager {
-  #queues = new Map<number, Promise<unknown>>()
+export interface LockOptions {
+  /** How long to wait for the lock before answering busy. */
+  timeoutMs?: number
+  retry?: RetryPolicy
+}
 
-  withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
-    return reentrant(id, fn, (run) => this.#acquire(id, run))
-  }
+/**
+ * An in-process FIFO per lock id with a bounded wait. Ownership passes straight
+ * to the next waiter on release, and a waiter that times out leaves the line.
+ */
+export class LockQueue {
+  #lines = new Map<number, Array<() => void>>()
 
-  async #acquire<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
-    const previous = this.#queues.get(id) ?? Promise.resolve()
-    let release!: () => void
-    const gate = new Promise<void>((resolve) => {
-      release = resolve
-    })
-    this.#queues.set(
-      id,
-      previous.then(() => gate),
-    )
-    await previous
+  async hold<T>(id: number, timeoutMs: number, fn: () => Promise<T>): Promise<T> {
+    await this.#acquire(id, timeoutMs)
     try {
       return await fn()
     } finally {
-      release()
-      if (this.#queues.get(id) === gate) this.#queues.delete(id)
+      this.#release(id)
+    }
+  }
+
+  #acquire(id: number, timeoutMs: number): Promise<void> {
+    const line = this.#lines.get(id)
+    if (!line) {
+      this.#lines.set(id, [])
+      return Promise.resolve()
     }
+    return new Promise<void>((resolve, reject) => {
+      const grant = () => {
+        clearTimeout(timer)
+        resolve()
+      }
+      const timer = setTimeout(() => {
+        const at = line.indexOf(grant)
+        if (at >= 0) line.splice(at, 1)
+        reject(new ContentBusyError('lockTimeout'))
+      }, timeoutMs)
+      line.push(grant)
+    })
+  }
+
+  #release(id: number): void {
+    const next = this.#lines.get(id)?.shift()
+    if (next) next()
+    else this.#lines.delete(id)
   }
 }
 
+/** Retries only from outside any transaction: one the database aborted cannot be resumed. */
+function guarded<T>(fn: () => Promise<T>, retry: RetryPolicy): Promise<T> {
+  return retryContention(fn, insideTransaction() ? { ...retry, attempts: 1 } : retry)
+}
+
+class SqliteLockManager implements LockManager {
+  #queue = new LockQueue()
+  #timeoutMs: number
+  #retry: RetryPolicy
+
+  constructor(options: LockOptions) {
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS
+    this.#retry = options.retry ?? DEFAULT_RETRY
+  }
+
+  withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
+    return reentrant(id, fn, (run) =>
+      guarded(() => this.#queue.hold(id, this.#timeoutMs, run), this.#retry),
+    )
+  }
+}
+
+/**
+ * The in-process queue first, then the advisory lock, which orders the nodes.
+ * Without the queue every waiting request held a pooled connection blocked on
+ * the advisory lock, and a pool full of waiters left the holder none to work on.
+ */
 class PostgresLockManager implements LockManager {
   #db: Db
-  constructor(db: Db) {
+  #queue = new LockQueue()
+  #timeoutMs: number
+  #retry: RetryPolicy
+
+  constructor(db: Db, options: LockOptions) {
     this.#db = db
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS
+    this.#retry = options.retry ?? DEFAULT_RETRY
   }
 
   withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
+    const timeout = Math.max(1, Math.round(this.#timeoutMs))
     return reentrant(id, fn, (run) =>
-      this.#db.transaction(async (tx) => {
-        await tx.exec('SELECT pg_advisory_xact_lock(?)', [id])
-        return run()
-      }),
+      guarded(
+        () =>
+          this.#queue.hold(id, this.#timeoutMs, () =>
+            this.#db.transaction(async (tx) => {
+              await tx.exec(`SET LOCAL lock_timeout = ${timeout}`)
+              await tx.exec('SELECT pg_advisory_xact_lock(?)', [id])
+              return run()
+            }),
+          ),
+        this.#retry,
+      ),
     )
   }
 }
 
-export function createLockManager(db: Db): LockManager {
-  return db.dialect.name === 'postgres' ? new PostgresLockManager(db) : new SqliteLockManager()
+export function createLockManager(db: Db, options: LockOptions = {}): LockManager {
+  return db.dialect.name === 'postgres'
+    ? new PostgresLockManager(db, options)
+    : new SqliteLockManager(options)
 }

package/src/migrations.ts

@@ -349,6 +349,26 @@ export async function readLedger(db: Db): Promise<LedgerRow[]> {
   }))
 }
 
+/**
+ * A step failed and was rolled back; every step before it is applied. Says which,
+ * and that running the upgrade again carries on from there.
+ */
+export class MigrationStepError extends Error {
+  constructor(
+    readonly step: string,
+    readonly applied: readonly string[],
+    readonly bundle: string | undefined,
+    override readonly cause: unknown,
+  ) {
+    const reason = cause instanceof Error ? cause.message : String(cause)
+    super(
+      `The upgrade stopped at ${bundle ? `the bundle "${bundle}"'s step` : 'step'} ${step}: ${reason}. ` +
+        `Nothing from that step was kept${applied.length > 0 ? `; the ${applied.length} step(s) before it are applied` : ''}. ` +
+        'Fix the cause and run the upgrade again: it carries on from this step.',
+    )
+  }
+}
+
 /** The database is at a state this code's plan does not know: newer code wrote it. */
 export class UpgradeStateError extends Error {
   constructor(
@@ -440,23 +460,29 @@ export async function migrate(
     await verifyApplied(db, plan, state)
     for (const next of pending) {
       const started = performance.now()
-      await db.transaction(async (tx) => {
-        await next.up(tx)
-        await next.backfill?.(tx)
-      })
+      // The state and the ledger row commit with the step, so an interrupted
+      // run resumes at the first step that did not land and never repeats one.
+      await db
+        .transaction(async (tx) => {
+          await next.up(tx)
+          await next.backfill?.(tx)
+          await writeState(tx, next.to, plan.stateKey)
+          await recordInLedger(tx, {
+            name: next.name,
+            kind: next.kind ?? 'expand',
+            fromState: next.from,
+            toState: next.to,
+            durationMs: Math.round(performance.now() - started),
+            checksum: next.checksum ?? next.name,
+            appliedBy: options.by ?? null,
+            note: next.release ? `release ${next.release}` : null,
+            bundle: plan.bundle ?? null,
+          })
+        })
+        .catch((error: unknown) => {
+          throw new MigrationStepError(next.name, applied, plan.bundle, error)
+        })
       state = next.to
-      await writeState(db, state, plan.stateKey)
-      await recordInLedger(db, {
-        name: next.name,
-        kind: next.kind ?? 'expand',
-        fromState: next.from,
-        toState: next.to,
-        durationMs: Math.round(performance.now() - started),
-        checksum: next.checksum ?? next.name,
-        appliedBy: options.by ?? null,
-        note: next.release ? `release ${next.release}` : null,
-        bundle: plan.bundle ?? null,
-      })
       applied.push(next.name)
     }
     return { from, to: state, applied }