---
title: Migrate
description: Authenticated state-graph migrations — review exact SQL, publish immutable estate states, and apply them with a marker and ledger
icon: git-branch
---

## When to Use Migrate

- **Production deployments** — the SQL you review is the SQL production executes
- **Team collaboration** — Git branches can diverge and merge without renaming files
- **CI/CD pipelines** — `check`, `status`, and `apply` have stable `--json` output
- **Recoverable apply** — interrupted work has one detectable state, not a guessed final status

`push` is a separate, history-free live sync. It never writes estate storage or the current-state marker. Use [Push](/docs/migration/push) for local prototyping; use migrate when the change must be history.

## What an Estate Is

One migration **state** is one graph node. It records a target schema **snapshot** and one authenticated transition from each parent. A linear state has one parent. A branch merge has one complete transition from every parent into the same target. Human names are labels only — they never decide order.

```
immutable estate descriptor
        +
content-addressed schema snapshots and SQL blobs
        +
immutable migration-state manifests
        +
database current-state marker
        +
append-only execution ledger
```

Production never evaluates migration TypeScript. It slices authenticated UTF-8 ranges from an authenticated SQL blob and binds the exact typed parameters sealed in each dispatch.

## Workflow Overview

```
1. Change your VibORM models
2. Generate a new estate state (review the SQL blob)
3. Apply that state to the database
4. status / verify / log explain the marker and ledger
```

## Composition Root

One migration client binds the database client to one optional estate storage.
There is no `$migrations` helper, migration manager, or
`createFsStorageDriver`.

**CLI**

```bash
# Default estate directory is ./migrations
npx viborm migrate generate --name add-users
npx viborm migrate apply
npx viborm migrate status --json
```

**Migration Client**

```ts
import { createMigrationClient } from "viborm/migrations";
import { createFsStorageWriter } from "viborm/migrations/storage/fs";
import { client } from "./client";

const migrations = createMigrationClient(client, {
  storage: createFsStorageWriter("./migrations"),
});

const generated = await migrations.generate({ name: "add-users" });
if (generated.outcome === "published") {
  console.log(generated.stateId, generated.sql);
}

await migrations.apply();
```

`createMigrationClient` is the only execution composition root. Its methods
reflect the supplied storage capability:

| Client construction | Available operations |
| --- | --- |
| No storage | `push`, `log` |
| `MigrationStorageReader` | The above plus `check`, `list`, `show`, `graph`, `status`, `verify`, `apply`, `down`, `baseline`, `reanchor`, `prune`, `resolve` |
| `MigrationStorageWriter` | Every operation, including `generate` and `reset` |

`log` reads the target database's append-only ledger. `push` is history-free.
Neither operation reads estate storage.

Every `viborm migrate` subcommand accepts `-d, --dir <dir>` and `--json`.
Use `viborm migrate --config ./path/viborm.config.ts <command>` to select the
configuration. `migrations.tables` and `migrations.resolve` apply to generation
and live synchronization; the table scope is immutable estate identity.
There is no migration-wide `--verbose` or `--force` flag. The operation
sections below list the remaining command-specific flags.

### Named Client and Result Types

The capability surfaces and operation results are exported for scripts and
tooling that keep their types in a central module:

```ts
import type {
  ApplyResult,
  GenerateResult,
  GraphResult,
  LiveMigrations,
  LogResult,
  ReadableMigrations,
  StatusResult,
  WritableMigrations,
} from "viborm/migrations";
```

Every operation has a named result: `GenerateResult`, `CheckResult`,
`ListResult`, `ShowResult`, `GraphResult`, `StatusResult`, `VerifyResult`,
`LogResult`, `ApplyResult`, `DownResult`, `BaselineResult`, `ResolveResult`,
`ResetResult`, `PushPreview`, and `PushApplyResult`.

## Generate a State

Generate compares the current models to the selected parent snapshot and publishes one new state. The first generate uses the virtual empty root. Later generates use the unique leaf, or every leaf when you are converging branches.

**CLI**

```bash
npx viborm migrate generate
npx viborm migrate generate --name add-users-table
npx viborm migrate generate --from empty
npx viborm migrate generate --dry-run --json
npx viborm migrate generate --name drop-legacy --accept-data-loss
```

**Migration Client**

```ts
const result = await migrations.generate({
  name: "add-users-table",
});

if (result.outcome === "published") {
  console.log(result.stateId);
  console.log(result.sql);
} else if (result.outcome === "noop") {
  console.log("Schema already matches the selected parent");
}

const preview = await migrations.generate({ dryRun: true });
// preview.outcome === "preview" — nothing is published
```

### Generate Options

| Option | CLI | API | Description |
|--------|-----|-----|-------------|
| Name | `--name <name>` | `name: string` | Human label. Metadata only; identity is the state hash. |
| Parent | `--from <stateId\|empty>` | `from: Sha256 \| null` | Full parent state id, or `null` / `empty` for the virtual root. |
| Estate directory | `--dir <dir>` | storage factory path | Estate root (default `./migrations`). |
| Dry run | `--dry-run` | `dryRun: boolean` | Return the complete candidate without publishing. |
| Resolver | `migrations.resolve` (config) | `resolve` | Answers ambiguous renames, enum value removals, and destructive changes (drops, type changes, NOT NULL tightening, narrower decimals, required columns without a default). |
| Manual artifact | — | `manualMigration` | Caller-owned transitions. No CLI flag. |
| Low-lock steps | `--low-lock` | `lowLock: boolean` | PostgreSQL: publish index builds and foreign keys on existing tables as recoverable steps. See [Indexes and foreign keys as steps](#indexes-and-foreign-keys-as-steps). |
| Adopt tables | `--adopt <table...>` | `adopt: string[]` | Bring existing tables under an estate with a `tables` list without DDL; apply proves each one equals its declaration. See [Adopt an Existing Table](#adopt-an-existing-table). |

`--from empty` and `from: null` mean the virtual empty root. On an estate that already has states, they author a checkpoint, which must restate the single leaf's schema; see [Bounded History with Checkpoints](#bounded-history-with-checkpoints). Numeric file indexes do not exist.

A state that removes several related tables drops each table before the tables it references, in the same order `push` uses; SQLite tables that no order can drop are refused before the state is published. See [Removing Related Tables](/docs/migration/push#removing-related-tables).

### Reviewing every branch

Generation returns `operationsByParent`, `warnings`, and `reviewSql`. Human
output prints every parent, its operations, rollback warnings, and labelled SQL
for checks, forward execution, and rollback. JSON retains the complete result.
Use `generate --review ./review.sql` to save that read-only projection or
`show <state> --sql --review ./review.sql` to regenerate it from the authenticated
estate. Review text is never parsed for execution; authenticated blob offsets
remain authoritative.

Ambiguous renames refuse without `migrations.resolve`, including converging
branches and renamed junctions. A rollback that would recreate a lost required
column without a default is explicitly irreversible: the tool cannot invent
the deleted data or a safe backfill.

### Destructive changes need an approval

Generate puts every destructive change to the resolver before it publishes,
exactly as push does. `change.proceed()` approves it; `change.reject()` or no
answer refuses with `V11010` and publishes nothing. Without a resolver, generate
refuses with `V11017` (`MIGRATION_CONSENT_REQUIRED`) and lists every change.
The approvals are saved in the published state: `show()` returns them as
`incoming[i].approvals` (type `MigrationApproval`: `{ operation, table, column }`)
and `reviewSql` prints `-- Approved at generate: …`. `apply` runs an approved
state without asking again. A `dryRun` without a resolver previews the state as
an approval would publish it: the preview's `stateId` is the id the approved
publish gets, and its `reviewSql` lists the approvals publishing will need as
`-- Needs approval at generate: …`. An `addAndDrop` answer approves its own
drop. States without a destructive change carry no approval and keep the ids
earlier versions gave them; for a destructive state the approvals are part of
its id. A destructive state published by 1.2.0 carries `approvals`; viborm 1.1.0
refuses to read it, so upgrade every machine and CI job that reads the history
together. With the CLI, `viborm migrate generate` asks once per destructive
change on a terminal, `--accept-data-loss` approves them all, and
`migrations.resolve` in `viborm.config.ts` answers instead of both.

```ts
await migrations.generate({
  name: "drop-legacy",
  resolve: (change) =>
    change.type === "destructive" ? change.proceed() : undefined,
});
```

### Decisions as data

`createPredefinedResolver(decisions)` builds that resolver from plain JSON, so
an API or an RPC call can carry a tenant's intent (type `MigrationDecision`).
Each decision names the change it answers by that change's own fields:

| Decision | Answers |
|----------|---------|
| `{ type: "column", tableName, from, to, resolution }` | The ambiguous column pair, with `"rename"` or `"addAndDrop"`. |
| `{ type: "table", from, to, resolution }` | The ambiguous table pair. |
| `{ type: "enumValueRemoval", tableName, columnName, mapValues }` | That column's removed enum values; `mapValues` maps each to a kept value or `null`. |
| `{ type: "destructive", operation, table, column }` | Approves that destructive change: the `MigrationApproval` identity, `column: null` for a table. |

A change no decision names is unanswered and refused, as without a resolver
(`V11010`). An entry that is not one of these shapes is refused when the
resolver is built (`V4002`), and `generate` refuses (`V4002`, nothing
published) a decision that answered no change of its plan: a table or column
the plan does not touch, or a change that is not there. A document already
published is a `noop` without that check, so resending the same document with
the same decisions is safe. A predefined resolver serves one request: build
one per `generate`.

```ts
import { createPredefinedResolver } from "viborm/migrations";

const decisions = [
  { type: "column", tableName: "account", from: "name", to: "displayName", resolution: "rename" },
  { type: "destructive", operation: "dropColumn", table: "account", column: "legacyCode" },
  { type: "enumValueRemoval", tableName: "account", columnName: "tier", mapValues: { legacy: "free" } },
] as const;

await migrations.generate({ resolve: createPredefinedResolver(decisions) });
```

### Manual Transitions

CLI authors can load the same checked manual input with
`migrate generate --custom ./migration.ts`. The module exports a default
`ManualMigrationInput`, or an async function receiving the readonly parent IDs
(`null` denotes the empty origin) and returning that input. Author code runs
only during generation. Production applies authenticated SQL and checks.


Some work moves data, not just structure. VibORM refuses to invent that movement. You supply complete parent transitions before generation. The estate stores the final SQL and closed manifest — not a durable TypeScript migration language.

```ts
import { sql } from "viborm";

const currentStateId = (
  await migrations.show({ name: "legacy-subject" })
).stateId;

await migrations.generate({
  name: "subject-to-many",
  manualMigration: {
    transitions: [
      {
        from: currentStateId,
        execution: "stepwise",
        originChecks: [
          {
            kind: "trusted-read",
            query: sql`SELECT NOT EXISTS (
              SELECT 1 FROM "content"
              WHERE "subject_type" <> 'content.post.v1'
            )`,
            equals: true,
          },
        ],
        up: [
          sql`CREATE TABLE "content_subject_post" (
                "contentId" text NOT NULL,
                "postId" text NOT NULL,
                PRIMARY KEY ("contentId", "postId")
              );`,
          sql`INSERT INTO "content_subject_post" ("contentId", "postId")
                SELECT "id", "subject_id" FROM "content"
                WHERE "subject_type" = 'content.post.v1';`,
        ],
        rollback: {
          kind: "manual",
          execution: "stepwise",
          sql: [sql`DROP TABLE "content_subject_post";`],
        },
      },
    ],
    destinationChecks: [
      {
        kind: "trusted-read",
        query: sql`SELECT NOT EXISTS (
          SELECT 1 FROM "content" AS c
          WHERE c."subject_type" = 'content.post.v1'
            AND NOT EXISTS (
              SELECT 1 FROM "content_subject_post" AS j
              WHERE j."contentId" = c."id"
                AND j."postId" = c."subject_id"
            )
        )`,
        equals: true,
      },
    ],
  },
});
```

This example uses PostgreSQL quoting. Adapt the SQL and physical scalar types
to the target dialect. Each check must return exactly one row and one
boolean-like column. An origin check proves the pre-transition fact; a
destination check proves the post-transition fact.

Rules, each a refusal rather than a warning:

- A state is wholly generated or wholly manual. Custom text is not spliced into generated DDL.
- Each `up` value is one opaque provider dispatch — VibORM does not split it on semicolons.
- `rollback` is `{ kind: "manual", execution, sql }` or `{ kind: "irreversible", reason }`. There is no `automatic` input arm.
- Stepwise manual work without complete origin and destination checks is refused before dispatch.
- A requested `transactional` boundary on a provider that cannot honor it is refused before effects.
- A blank irreversible reason is refused.

A data-only transition can create a new state while keeping the same schema snapshot. Equal snapshots never prove equal migration state.

## Inspect the Graph

These commands do not apply SQL. `check` is offline. `list`, `show`, and `graph` read the estate.

**CLI**

```bash
npx viborm migrate check --json
npx viborm migrate list --json
npx viborm migrate show add-users --json
npx viborm migrate graph --json
```

**Migration Client**

```ts
const check = await migrations.check();
if (!check.ok) {
  for (const finding of check.findings) {
    console.error(finding.code, finding.message);
  }
}

for (const state of await migrations.list()) {
  console.log(state.stateId, state.name);
}

const shown = await migrations.show({ name: "add-users" });
console.log(shown.snapshotHash, shown.sqlHash);
console.log(shown.root, shown.leaf);
console.log(shown.incoming, shown.outgoing);

const graph = await migrations.graph();
console.log(graph.estateHash, graph.target);
console.log(graph.roots, graph.leaves);
console.log(graph.states, graph.edges);
```

`show` and `apply({ to })` accept a full state id, an unambiguous prefix, or an unambiguous name. Ambiguous names or prefixes refuse. Numeric indexes are not selectors.

`list` is the compact state-id/name view. `show` adds the snapshot and SQL
identities, root/leaf flags, and incoming/outgoing edge metadata. `graph`
returns the estate target, every state, and every edge. Edge metadata exposes
the parent and child ids, transition hash, requested execution boundary,
operation and step counts, origins, risks, and rollback kind. These are frozen
descriptions, not executable plans or mutable manifest objects.

## Status, Verify, and Log

`status`, `verify`, and `log` are read-only. They never create control tables and never translate a provider failure into “no migrations applied.”

**CLI**

```bash
npx viborm migrate status --json
npx viborm migrate verify --json
npx viborm migrate log --limit 20 --json
```

**Migration Client**

```ts
const status = await migrations.status();
// status.control === "absent" | "present"
// status.marker — last confirmed state, or null
// status.pending — unique-leaf path from the marker, when one leaf exists
// status.unfinished — an attempt is still open on the ledger
// status.markerState — "ahead" | "unknown", only when the marker names a state this estate does not hold
// status.invalidIndexes — [{ table, index }], only when a managed table has an INVALID PostgreSQL index
// status.lastFailure — the latest `failed` ledger event, once an attempt failed and rolled back

const verify = await migrations.verify();
const events = await migrations.log();
```

| Command | Lock | What it answers |
|---------|------|-----------------|
| `status` | no | Marker, pending path to the unique leaf, unfinished attempts, a marker this estate does not hold (`markerState`), INVALID PostgreSQL indexes (`invalidIndexes`), and the latest failed attempt (`lastFailure`). |
| `verify` | yes | Live managed schema matches the marker's authenticated snapshot. A marker this estate does not hold returns `{ ok: false, markerState }`. |
| `log` | no | Authenticated database-ledger events in causal order: by time, then attempt by attempt along the state chain, and within an attempt its start, steps and end. A transactional apply records one `applied` event per state; stepwise and MySQL applies also record `started` and per-step events. It does not inspect estate artifacts. |

CLI `log --limit <n>` keeps the last `n` events after that stable ordering. The
programmatic `log()` call returns the complete ledger so callers can slice or
filter it themselves.

A transactional attempt that fails rolls back with everything it wrote, its own
ledger events included. `apply` then records it in a transaction of its own as a
`failed` ledger event (creating the control tables first when the failed attempt
was the first apply): its `fromState`/`toState`, the `dispatchId` and
`operationId` of the statement the provider refused, and a `failure` line with
the error code and message. `status().lastFailure` returns the latest one,
also after a later `apply` succeeded: it is history, not current state. A
`failed` event closes its attempt: once the cause is fixed, `apply` runs again,
even when no marker exists yet. A stepwise failure is different: its effects
stay, its attempt stays unfinished, and it is recovered with `resolve` (see
below).

Drift is read in the snapshot's vocabulary, from what the database enforces.
Two SQLite facts that are easy to make by hand read as drift: a table stored
`WITHOUT ROWID` under a model that does not declare
[`.withoutRowid()`](/docs/schema/model) (or the reverse), and a key column
declared without `NOT NULL` in an ordinary rowid table, which SQLite lets hold
NULL (only an `INTEGER PRIMARY KEY`, the rowid itself, cannot), so it reads as
nullable while the model's ID is not. VibORM writes every key column `NOT
NULL`, so the tables it made are unaffected.

There is no `pending()` method. Pending work is a field on `status()`.
`log()` requires an existing, authentic control-table pair. When it is absent,
`log()` throws `MIGRATION_NOT_FOUND`; it does not return an empty successful
log.

## Apply

Apply authenticates the selected path, refuses live drift, executes exact SQL slices, then compare-and-swaps the marker. The default target is the unique leaf. Multiple leaves require `--to` / `{ to }`. Multiple routes require `--via` / `{ via }`.

**CLI**

```bash
npx viborm migrate apply
npx viborm migrate apply --to add-users
npx viborm migrate apply --to a1b2c3d4
npx viborm migrate apply --via <stateId> --to <stateId>
npx viborm migrate apply --dry-run --json
```

**Migration Client**

```ts
const applied = await migrations.apply();
console.log(applied.outcome, applied.path);

await migrations.apply({ to: { name: "add-users" } });
await migrations.apply({ to: { prefix: "a1b2c3d4" } });
await migrations.apply({ to: { id: fullStateId } });
await migrations.apply({ dryRun: true });
```

### Code Older Than the Database

When the database marker names a state this estate does not hold, `status()`
reports `markerState: "ahead"` (its arrival path leaves this history after a
state it holds: newer code migrated the database, or a Durable Object's estate
was restored behind Postgres) or `"unknown"` (nothing on that path belongs
here), with `pending: []`. `apply()` refuses both with `V11002` by default;
`apply({ ifAhead: "noop" })` returns `{ outcome: "noop" }` for an ahead marker
without touching the database, so old code can boot against a newer schema. An
unknown marker is always refused. When the history is the side a restore left
behind, see [History older than the database](#history-older-than-the-database).

### Apply Options

| Option | CLI | API | Description |
|--------|-----|-----|-------------|
| Target | `--to <selector>` | `to: StateSelector` | Full id, unambiguous prefix, or unambiguous name. |
| Via | `--via <stateId...>` | `via: Sha256[]` | Force a path through these full state ids. |
| Estate directory | `--dir <dir>` | storage factory path | Estate root. |
| Dry run | `--dry-run` | `dryRun: boolean` | Plan without executing. Zero database effects. |
| Marker ahead | — | `ifAhead: "noop" \| "refuse"` | `"noop"` returns a `noop` outcome when the marker is ahead of this estate. Default `"refuse"`. |

There is no `--force`, no numeric `--to 5`, and no tracking-table name flag. Control tables are `_viborm_migration_state` and `_viborm_migration_log`.

If the marker is absent, ordinary apply requires the managed target to be empty apart from control objects. Adopting an existing schema is `baseline`, not an implicit first apply.

On PostgreSQL an `apply` with nothing to do sends 2 statements: the control tables' definition, then one statement that reads the marker, any unfinished attempt and a digest of the managed schema computed by the server, while no other migration command holds the lock. It still proves there is no drift: a digest that does not match is decided again under the lock, which names the difference. Partial-index predicates are compared as PostgreSQL deparses them (`"deletedAt" IS NULL` reads back as `("deletedAt" IS NULL)`), against the text the apply that reached the state read from the catalog and stored beside the marker. A marker without that text (written by 1.1.0, or by a command other than `apply`), a server that now deparses a predicate differently (after a major upgrade), and a schema the digest cannot reproduce (some literal defaults) get the same answer from the locked proof, in about 30 statements.

A statement the migration dispatches that the database refuses fails the command with `MigrationError` V11001 (`MIGRATION_FAILED`). Its `meta` names `step` (`apply`, `down`, `resolve`, `reset-clear` or `reset-replay`), `stateId`, `fromState`, `toState`, `strategy` (the boundary: `transactional`, `stepwise` or `atomic`), `operationId`, `dispatchId`, `statementIndex` and the provider's `providerCode`/`providerSqlState`, and its `cause` is the provider error. Any other failure of `apply`, `down`, `reset`, `reanchor`, `resolve` or `baseline`, a lost connection or a lock wait, keeps its own class and code and still carries the `step` it happened in (and, inside an `apply` or `reset` transaction, its `strategy` and `stateId`). The provider's text, and with `includeSql` the statement in `meta.query`, are disclosed when the client handed to `createMigrationClient` carries [instrumentation](/docs/extensions/instrumentation)'s `diagnostics`; otherwise they are redacted. A transactional attempt rolls back and is recorded as `failed` (see `status().lastFailure`). When a COMMIT's reply is lost, apply re-reads the marker: `applied` when it shows the commit, V11020 when it cannot be read. A COMMIT the database refuses (for example a deferred constraint) keeps its provider error. When ending the session fails after the commit, apply returns `applied` with `warnings`.

## Roll Back

`down` follows the marker's actual arrival path. It cannot invent a parent this database never used, and it cannot cross a baseline boundary.

Rollback does **not** restore discarded data. Generated destructive changes restore managed schema shape only.

| Stored rollback | Meaning |
|-----------------|---------|
| `schema` | Invert the generated operations. Structure returns; rows created after the forward migration may be gone. |
| `manual` | Author-owned reverse dispatches and checks. |
| `irreversible` | No reverse transition. `down` refuses and quotes the reason. |

**CLI**

```bash
npx viborm migrate down
npx viborm migrate down --steps 1
npx viborm migrate down --to add-users
npx viborm migrate down --steps 1 --expect-revision 4 --accept-data-loss
npx viborm migrate down --dry-run --json
```

**Migration Client**

```ts
await migrations.down({ to: { name: "add-users" } });

const { marker } = await migrations.status();
await migrations.down({ steps: 1, expectRevision: marker?.revision });

await migrations.down({
  to: { name: "add-users" },
  resolve: (change) =>
    change.type === "destructive" ? change.proceed() : undefined,
});
await migrations.down({ steps: 1, dryRun: true });
```

**Automation uses `down({ to })`.** An absolute target is idempotent: a retry
after a lost reply finds the marker already there and returns `{ path: [] }`. A
relative `down({ steps })` retried the same way would roll back one more state,
so pass `expectRevision`, the `marker.revision` you read: when another command
moved the marker since, `down` refuses with `V11015`
(`MIGRATION_MARKER_CONFLICT`) before any effect.

**Rolling back over data asks first.** When a generated rollback is
destructive (it drops a table or column, narrows a type, …), `down` compares
the two states' snapshots; for each destructive change on a table that holds
rows, it puts the change to `resolve`, as `generate` and `push` do:
`change.proceed()` approves it, `change.reject()` or no answer refuses with
`V11010`, and a `down` without `resolve` refuses with `V11017`
(`MIGRATION_CONSENT_REQUIRED`), listing the changes. The reads run under the
lock, before the first rollback statement. A rollback over empty tables needs
no answer, and neither does a table that is absent: a later state dropped it
(an earlier step of the rollback recreates it empty), or an interrupted
rollback already did. A manual rollback is not asked again: its author wrote
and published that SQL, often to move the rows back before a drop. The CLI
asks on a terminal; `--accept-data-loss` or `migrations.resolve` in
`viborm.config.ts` answers instead.

**Preview a rollback.** `down({ dryRun: true })` changes nothing and returns,
for each edge in the order `down` would roll it back, its rollback SQL
(`edges[i].sql`, rendered as `show --sql` renders it) and `refusal`: the
`{ code, message }` that `down` with the same options would raise before its
first effect, or `null`. It runs the same read-only checks: an irreversible
step (`V11010` with its reason), a loss of rows not approved by `resolve`
(`V11017` or `V11010`), drift, and an unfinished attempt `down` cannot resume
(a forward attempt, or more than one: `V11016`). `viborm migrate down --dry-run`
prints the SQL, prints the refusal on stderr and exits non-zero where `down`
would refuse. A rollback that finished but was not recorded is closed by
`down` without rolling anything back; its preview still shows the selected
path.

The results of `status()`, `log()`, `show()`, `resolve()` and the `down`
preview are plain data: they survive `structuredClone` and JSON, so a Durable
Object or any RPC boundary can return them as they are.

`down` is the only rollback verb. There is no tracking-only `rollback()`, `drop`, or `pending()` untrack. Removing a marker row while the schema stays live is not a supported operation.

## Baseline an Existing Database

`baseline({ to })` adopts a live database that already matches an estate state. It executes no migration SQL.

Under the target lock it requires:

- no existing marker or ledger history
- exact live physical equality with that state's snapshot
- a complete structural root path to that state
- no manual, opaque, or data-only transition on that path

**CLI**

```bash
npx viborm migrate baseline --to add-users --json
```

**Migration Client**

```ts
await migrations.baseline({ to: { name: "add-users" } });
```

The marker records a baseline path boundary so later `down` cannot invent an arrival parent.

## Adopt an Existing Table

An estate created with a `tables` list (say, on a Durable Object whose
database also holds FTS5 tables you manage yourself) records that list in
`estate.json`. The list may only grow afterwards: a client can list every
table of the estate's list plus new ones. A name of the estate's list missing
from the client's, or a list on one side only, refuses with `V11004`, which
says which.

Growing the list does not hand the new names to the estate. Every history
command (`apply`, `down`, `verify`, `status`, `baseline`, `reanchor`,
`resolve`, `reset`) selects only what the estate manages: its own list plus
the tables of the states the command proves, never the client's list. A table
only the client lists is still yours, and no command reads, proves or drops
it. `push` is history-free and keeps selecting the client's list.

A new model on a grown list is an ordinary `CREATE TABLE` state. To bring a
table you already created by hand (a `CREATE TABLE IF NOT EXISTS` bootstrap,
say) under the estate instead, declare its model, list it, and adopt it when
you generate:

Adopt a table you made by hand rather than generating that `CREATE TABLE`
state over it. `apply` does refuse the hand-made table (`V11014`) when the
first state it applies creates it, and SQLite refuses the `CREATE TABLE`
itself and rolls everything back (`V11001`). But on MySQL and Neki, where each
statement commits on its own, a later state of the same `apply` skips the
`CREATE TABLE` of a table that already exists: that skip is how an interrupted
`apply` resumes. A table equal to the declaration is then managed from that
state on, with its rows and any triggers or settings it has, without the
checks below. A different table stops the `apply` with `V11019`, after the
earlier statements have committed.

**CLI**

```bash
npx viborm migrate generate --name adopt-dependency --adopt dependency
npx viborm migrate apply
```

**Migration Client**

```ts
const migrations = createMigrationClient(client, {
  storage,
  tables: ["users", "dependency"], // the estate was created with ["users"]
});
await migrations.generate({ name: "adopt-dependency", adopt: ["dependency"] });
await migrations.apply();
```

Each adopted name must be a table the schema declares, absent from every
parent state, and outside the estate's own list: a table of that list is
managed already, so a raw one of that name is drift (`V11014`), not something
to adopt. An estate without a list manages the whole database and adopts
nothing. `adopt` is refused with `manualMigration`, `lowLock`, and on a
checkpoint.

The transition records the names in an `adopts` field (shown by `show` and in
the review SQL) and emits no DDL for the table, its indexes or its foreign
keys. `apply` proves the origin without it, then proves the destination with
it: the live table must equal the declaration in what a schema snapshot
states — its columns (name, type, nullability, default, auto-increment), its
primary key, indexes (name, columns, uniqueness, method, partial predicate),
unique constraints, foreign keys (columns, target, `ON DELETE`/`ON UPDATE`),
and SQLite's `WITHOUT ROWID` ([`.withoutRowid()`](/docs/schema/model)). A
table that differs fails with `V11014` and its differences before the marker
moves; nothing ran, and the table and its rows are untouched. Fix the table or
the model and apply again. Rows are kept. From then on the table is managed
like any other.

Some of what a hand-made table can carry changes how it behaves and is not in
that vocabulary, so before any effect every command that brings an adoption
into the estate (`apply`, `baseline`, `reanchor`, `resolve` when it completes
or retries the adopting state, and a `reset` replaying the adoption) also
refuses, with `V11014` naming the table and the feature, an adopted table that
has:

- on SQLite: a trigger, `STRICT`, an `ON CONFLICT` clause (on the key, a NOT
  NULL or a UNIQUE: `REPLACE` would overwrite a row a create should refuse),
  or a column collation other than `BINARY`. A CHECK constraint is refused by
  every SQLite command already (`V11009`), as is a non-`BINARY` collation on a
  key or index column (`V8001`).
- on PostgreSQL: a trigger, a rule, row-level security (enabled or forced),
  `UNLOGGED` storage, a CHECK constraint, a `DEFERRABLE` key, or a column
  collation other than its type's default (the declaration writes no
  `COLLATE`, so the database default is what it states).
- on MySQL: a trigger, a CHECK constraint, an engine other than InnoDB, or a
  table or column collation other than `utf8mb4_0900_bin`, the one VibORM's
  `CREATE TABLE` writes (a table made with the database default
  `utf8mb4_0900_ai_ci` compares case-insensitively, and the columns VibORM
  adds later would take it).

Only the tables a transition adopts are read this way: a managed table keeps
whatever triggers or settings you give it, and `verify` and every other
command behave as before.

`down` of an adopting state releases the table: no DDL runs, its rows stay,
and the parent state no longer manages it. Applying again adopts it again,
with the same proof.

A raw table whose foreign key references a managed table crosses the managed
boundary and is refused before any effect, as before; adoption does not lift
that rule. Drop that key, adopt the table, then declare the relation: the next
state adds the key as ordinary DDL.

## Recover an Unfinished Attempt

An unfinished ledger attempt means the live schema may be between states. Ordinary apply and down refuse until you recover.

`resolve` is not checksum repair. It changes the marker only when live proof permits:

| Outcome | CLI | Required proof |
|---------|-----|----------------|
| Complete | `--complete` | Remaining postchecks, destination checks, and the target fingerprint hold. |
| Rolled back | `--rolled-back` | Origin checks and the origin fingerprint hold, and no manual opaque step of the attempt committed or may have committed. |
| Retry | `--retry` | Resume from the first step whose postcheck is false and precheck is true. |

```bash
npx viborm migrate resolve --complete --json
npx viborm migrate resolve --rolled-back --json
npx viborm migrate resolve --retry --json
```

Equal physical fingerprints are not proof for a data-only or opaque transition. If that transition omitted the checks that distinguish its two states, `resolve` refuses.

`--rolled-back` also reads the attempt's ledger. When one of its manual
(opaque) steps committed (`V11019`, `MIGRATION_PARTIAL_EFFECT`) or was announced and never
confirmed, so it may have committed (`V11020`), `resolve` refuses: no rollback
undid that step, no fingerprint shows a data change, and marking the attempt
rolled back would let `apply` run the step a second time — a balance credited
twice. The refusal names the `dispatchId`; finish the transition by hand and
`resolve --complete`. A `CONCURRENTLY` index statement is the exception (see
below): `resolve` repairs the index it names first, and the origin fingerprint
then proves it undone.

A manual step the database refused whole — one statement, such as a unique-key
violation or a `lock_timeout` — committed nothing. It fails with `V11001`
(`MIGRATION_FAILED`, `meta.partial: true`), its refusal is recorded in the
ledger, and `--rolled-back` closes its attempt once the origin checks hold. A
`CALL`, `DO`, `EXECUTE` or `CONCURRENTLY` step can commit part of its work
before it fails, so its failure stays `V11020`.

An attempt closed as rolled back, resolved or failed no longer blocks anything:
`apply` starts again, even when the failed attempt was the first one and no
marker exists yet.

### Interrupted `CREATE INDEX CONCURRENTLY`

A failed or interrupted `CREATE`/`REINDEX INDEX CONCURRENTLY` leaves the index
INVALID: PostgreSQL maintains it on writes but never reads through it.
`status()` and `log()` keep working and `status().invalidIndexes` names it;
`verify`, `apply` and `push` refuse with `V11023` (`MIGRATION_INVALID_INDEX`),
naming the index. When the unfinished attempt's own statement named that index,
`resolve` repairs it before its proof: `--rolled-back` drops it with
`DROP INDEX CONCURRENTLY`, and `--complete` rebuilds an index the destination
declares with `REINDEX INDEX CONCURRENTLY` (PostgreSQL 12+), otherwise drops it.
The `<name>_ccnew` / `<name>_ccold` copies an interrupted `REINDEX CONCURRENTLY`
leaves behind are dropped the same way. `resolve` never touches an invalid index
the attempt did not name, or an unnamed build: another session's build may still
be running. Drop or rebuild that index yourself, then resolve.

### History Older Than the Database

A restore can leave the history and the database at different points.

- **The database is older** (it was restored from an earlier backup): nothing
  needs repair. The marker names a state the history holds, and `apply` runs
  the states the database lacks.
- **The history is older** (the estate directory, or a Durable Object's
  storage, was restored from an earlier backup): the marker names a state the
  history lacks. `status().markerState` is `"ahead"` or `"unknown"`, and
  `apply` refuses with `V11002`.

The cheaper repair comes first. State ids are content-addressed. Generating the
lost states again, with the same schema documents, names, parents and decisions
and the same VibORM version, reproduces their ids exactly. The marker is then
known again, and nothing else is needed. Keep every schema document and its
decisions somewhere durable so this stays possible.

Otherwise, generate the schema the database runs as a state of the history you
have. Its id differs from the lost one, because its parent or its name does.
Then re-anchor the marker on it:

**CLI**

```bash
npx viborm migrate reanchor --json
npx viborm migrate reanchor --to add-users --json
```

**Migration Client**

```ts
const { stateId } = await migrations.reanchor();
await migrations.reanchor({ to: { name: "add-users" } });
```

Under the target lock, `reanchor` moves the marker onto the one state of this
history whose snapshot the live schema matches exactly, by the fingerprint
`verify` compares. It runs no migration SQL. It refuses in these cases:

- The marker names a state this history holds (`apply` and `verify` handle
  it), or there is no marker (use `baseline`). `V11009`.
- An attempt is unfinished: resolve it first. `V11009`.
- No state matches the live schema. `V11014`, with the differences from the
  history's latest state.
- Several states match. Equal schemas never say which data the database
  holds. `V11009`, naming them.
- The route from the root to the state has a manual, opaque or data-only
  transition, as for `baseline`. `V11009`.
- The marker's own path passed through the state: the transitions lost after
  it changed no schema, so they may have moved data, and moving back would
  run them again. Regenerate the lost states instead. `V11009`.

The new marker path starts at the history's root with a baseline boundary, as
`baseline` records it, so `down` cannot cross it. The ledger records a
`reanchored` event, whose `fromState` is the state the marker named before.

`reanchor({ to })` adopts the named state as the new baseline. It is the
explicit consent to take the live schema as that state, which several matching
states need. It still requires exact live equality and a structural route.

## Bounded History with Checkpoints

Every command loads the whole history, and the marker records the whole path
the database took. A history of hundreds of states keeps growing both. An
authored checkpoint bounds them: a second root whose one transition creates the
current schema from empty, so the states before it are no longer needed.

1. **Author the checkpoint.** On the estate, generate from the empty root. The
   checkpoint must restate the schema of the estate's single leaf: generate any
   schema change first, then the checkpoint.
2. **Prune into a fresh history.** `prune` copies the checkpoint, every state
   after it, and the snapshots and SQL they reference into another storage. The
   source history is never changed: storage is append-only, so pruning is a
   copy. The copy holds nothing `check()` would report as an orphan.
3. **Switch to the fresh history and re-anchor each database.** Its marker
   names a state the fresh history does not hold (`status().markerState` is
   `"unknown"`, and `apply` refuses with `V11002`). `reanchor()` proves the
   live schema equals the checkpoint's snapshot and moves the marker onto it,
   with a baseline boundary, as in
   [History Older Than the Database](#history-older-than-the-database).

```ts
import { createMigrationClient } from "viborm/migrations";
import { createFsStorageWriter } from "viborm/migrations/storage/fs";

const history = createMigrationClient(client, {
  storage: createFsStorageWriter("./migrations"),
});
await history.generate({ name: "checkpoint-2026-10", from: null });
await history.prune({
  checkpoint: { name: "checkpoint-2026-10" },
  into: createFsStorageWriter("./migrations-next"),
});

// After replacing ./migrations with ./migrations-next, for each database:
const migrations = createMigrationClient(client, {
  storage: createFsStorageWriter("./migrations"),
});
if ((await migrations.status()).markerState === "unknown") {
  await migrations.reanchor();
}
await migrations.apply();
```

`prune` returns `{ states }`, the states the fresh history now holds. Running
it again into the same storage publishes nothing new. It is an API only: there
is no `viborm migrate prune`. A Durable Object prunes into its own storage
under a key prefix: see
[the tenant migrator](/docs/migration/tenant-migrator#bounded-history).

Before you prune:

- **Apply the leaf everywhere.** A database still behind the checkpoint's
  schema cannot be re-anchored: `reanchor` refuses with `V11014`. Apply it with
  the old history first, which `prune` left untouched, then re-anchor. Where
  its data can go, [`reset`](#reset) clears it and replays the fresh history
  instead.
- **Resolve unfinished attempts.** `reanchor` refuses while one is open, and
  `resolve` needs the states the attempt names.
- **Generate after the checkpoint from it.** Between the checkpoint and the
  switch, the old history has two leaves, so `apply` needs `{ to }` and
  `generate()` without `from` merges both leaves. A state that merges older
  history keeps it: `prune` copies every parent a kept state names.

`down` cannot cross the checkpoint, as it cannot cross a baseline. The ledger
keeps its events about the dropped states.

## Reset

`reset` preloads and authenticates the complete clear-and-replay program before the first drop. It keeps the estate, both control tables, every ledger event, and the old marker until final success. On PostgreSQL, the replay commits after each migration that adds enum values, so a later migration can use them. If it is interrupted after such a commit, running `reset` again resumes from the recorded progress.

**CLI**

```bash
npx viborm migrate reset --dry-run --json
npx viborm migrate reset --confirm --to add-users
```

**Migration Client**

```ts
await migrations.reset({ dryRun: true });
await migrations.reset({ to: { name: "add-users" } });
```

:::warning[Destructive]
Reset drops managed objects, then replays authenticated states. Effectful CLI reset requires `--confirm`. Dry-run reads the actual selected
physical table inventory, returns it as `tables`, and writes nothing.
:::

On an estate with a `tables` list, what `reset` drops is the estate's list
plus every table its marker's path managed, never a table only the client
lists: a table you have not adopted yet survives a reset with its rows. A
replayed adoption of such a table proves it as `apply` does. A replay that
would adopt a table the clear drops (it was managed at the marker) is refused
before any effect: an adoption has no DDL to recreate it.

`reset` also works on a database whose marker names a state this estate does
not hold (`status().markerState` is `"ahead"` or `"unknown"`, say after the
estate was replaced by a fresh history): what it drops is the live inventory,
which needs no snapshot of the old state, and its dry run and its run plan the
same clear and replay. Before 1.4.3 the run refused with `V11022`. On an
estate with a `tables` list that inventory is the estate's list plus the
tables of the states this estate holds on the marker's path: a table the old
history created through its own grown list cannot be told from one you made
and have not adopted. When the replay creates such a table and it exists,
`reset` (and its dry run) refuses before any effect with `V11009`, naming the
table (`meta.table`); it never drops it. Drop or rename it yourself if its
rows can go, then reset again. The same refusal covers a table you made by
hand that a later state of this estate creates.

There is no squash or inferred compaction command. History is bounded by an explicitly authored, fully checked direct transition instead: see [Bounded History with Checkpoints](#bounded-history-with-checkpoints).

## Push Does Not Create History

```ts
const live = createMigrationClient(client);
const preview = await live.push({ dryRun: true });
await live.push({ consent: preview.consent });
```

`push` plans from the live catalog, replans under the target lock, and executes the accepted in-memory program. It never reads or writes estate storage and never changes the marker or ledger.

A non-empty push against a valid migration marker is refused. A no-op is allowed only when the marker, unfinished-attempt state, desired snapshot, live fingerprint, and empty diff all agree. That is not `verify`.

See [Push](/docs/migration/push) for consent, force-reset, and dry-run.

## Estate Layout

```
migrations/
├── estate.json
├── snapshots/
│   └── <snapshot-hash>.json
├── sql/
│   └── <sql-hash>.sql
└── states/
    └── <state-id>.json
```

`estate.json` is created once and is immutable: format `"1"`, hash `"sha256"`, and the exact `MigrationTarget`. PostgreSQL estates are schema-bound. MySQL artifacts stay database-relative. SQLite keeps its dialect target.

Snapshots, SQL blobs, and state manifests are content-addressed. A state becomes visible only after its snapshot and SQL bytes are durable and the manifest is published through an atomic no-replace boundary. Filenames that look like hashes are not proof — every read recomputes the chain.

### Incremental snapshots

Generation stores the first schema as a full snapshot. Later states store a
structured delta against a selected parent artifact when that delta is smaller
than the full schema. A full checkpoint limits reconstruction to 32 delta links.
Large or widespread changes can therefore produce a full snapshot. No option
or conversion command is needed, and existing full snapshots remain valid.
Engines that predate incremental snapshots cannot read the new delta manifests;
upgrade every estate reader before generating them.
Authored history checkpoints (`generate({ from: null })`) always use a full
snapshot. Low-lock split generation applies the same encoding to every step.

The state's `snapshotHash` always identifies the complete canonical schema.
A delta has its own content address, recorded as `snapshotArtifactHash` in the
state manifest. Two branches can reach the same schema through different
delta artifacts without conflicting over a storage key. A state whose parent
already stores its schema, such as a data-only migration, reuses the parent's
representation. The representation depends only on the parents, so generating
a state again reproduces its id.

All dependent artifacts are authenticated and reconstructed into full schema
snapshots before migration execution. Missing or changed bases fail before
effects. `check` also validates unused artifacts and counts transitive bases as
referenced. Keep the entire estate when copying or bundling migrations.
The `prune` operation copies all physical dependencies needed by retained
states, including a base whose original migration state is no longer retained.

This reduces repeated snapshot JSON on disk. It does not reduce the number of
migrations or SQL statements, and savings depend on schema size and changes.

There are no numbered `0001_*.sql` files, no `meta/_journal.json`, no latest snapshot, and no `meta/_down/` tree. Forward SQL, rollback SQL, and checks live in one SQL blob; the state manifest points at exact byte ranges.

### Storage Requirements

- Reads and inventories are strongly consistent.
- Publishing the same bytes at an existing identity is idempotent.
- Different bytes at an existing identity are corruption.
- The filesystem writer uses write-temp → fsync → hard-link no-replace. Check-then-rename is not a V1 publication.
- Eventually-consistent or last-writer-wins stores (including Workers KV) are not writable estate backends. Object stores need conditional writes and strong listing.

## Provider Limits

No provider inherits a guarantee from its dialect name. Effectful work requires a proven marker compare-and-swap, execution boundary and migration lock: a transaction-scoped advisory lock on PostgreSQL, a session lock on MySQL, and on SQLite the write lock of `BEGIN IMMEDIATE` (on a Durable Object, one platform transaction per frame).

| Provider | Effectful migrate / push | Notes |
|----------|--------------------------|--------|
| PGlite, `pg`, postgres.js, Bun SQL | Yes, when lock/CAS is proven | Transactional when every statement permits it. Each transaction takes the lock and the marker is read under it, so a transaction pooler (PgBouncer in transaction mode) works; stepwise work keeps a session lock and needs a direct session. See [PostgreSQL](/docs/migration/drivers/postgresql#guarantees-and-limits). |
| SQLite3, Bun SQLite | Yes; stepwise refused | The write lock of `BEGIN IMMEDIATE` is the migration lock: each command reads the marker and the unfinished attempts as the first statements of the transaction that runs its first group, so a second `apply` of the same state, from any process, reports `noop` or refuses with `V11015`. `generate` refuses a manual transition or rollback declared `execution: "stepwise"` (`V11021`), and `apply`, `down` and `reset` refuse one 1.1.0 published. See [SQLite](/docs/migration/drivers/sqlite#concurrent-commands). |
| MySQL2 | Stepwise | DDL implicitly commits. Nominal transactions do not create rollback. Progress is recorded per dispatch. |
| Neon HTTP | `apply` only | No interactive session: each transactional group is one request, a non-interactive transaction that takes the lock and asserts the marker, the checks and the destination's catalog digest in SQL. Stepwise transitions and a destination the digest cannot prove (a partial index) refuse with `V11021`; a lost reply is decided by the marker, else `V11020`. down/reset/verify/push refuse (`V8002`). See [Neon HTTP](/docs/drivers/postgresql/neon-http#migrations). |
| PlanetScale | Read-only / offline | VTGate routing does not prove containment. Same offline/read-only split. |
| Durable Object (`viborm/durable-object`) | Yes; stepwise refused | The migration lock is one `ctx.storage.transaction()` per frame, held open by the migration, and the migration holds the driver's queue; a raw `ctx.storage.sql.exec` joins the open frame. See [Durable Objects](/docs/drivers/sqlite/durable-object#migrations). |
| D1 | Effectful refused until proven | Table recreation, foreign keys, native-batch atomicity, and marker CAS are not proven together. |
| LibSQL | Effectful refused until proven | Existing-row constraint validation and safe table reconstruction are not proven. |

VibORM never generates `CREATE INDEX CONCURRENTLY`. A manual transition that
uses it must declare `execution: "stepwise"`, which sends each `up` dispatch on
its own, outside a transaction. `generate` refuses (`V11012`) a dispatch declared
`"transactional"` that PostgreSQL cannot run inside a transaction, naming it:
`CREATE [UNIQUE] INDEX`, `DROP INDEX` or `REINDEX INDEX|TABLE|SCHEMA|DATABASE`
with `CONCURRENTLY`, `REINDEX (…, CONCURRENTLY)`, and `DETACH PARTITION …
CONCURRENTLY`. A manual rollback is held to its own `execution`.
A state an earlier version published that way still fails at `apply`: PostgreSQL
rejects the statement (SQLSTATE 25001) with `V2001` and the transaction rolls back.
`ALTER TYPE … ADD VALUE` runs inside the transaction; an edge that adds
an enum value ends its commit group, so a later edge can use the new value.

Interrupted stepwise work is explainable from the ledger. The tool never reports rollback that the provider could not perform.

## Large Tables

Some PostgreSQL changes rewrite or scan the whole table while holding a lock
that blocks it, so their duration grows with the table:

- a column type change, including an enum replacement and a decimal descriptor change;
- `SET NOT NULL`;
- a new column whose default is volatile, such as `gen_random_uuid()` or a serial;
- a `FOREIGN KEY` or `CHECK` constraint added without `NOT VALID`.

Above `limits.largeTableRows` (default 1,000,000), `apply`, `down` and
`push`, including push's dry run, refuse such a change before any statement
runs, with `V11009` naming the operation, the table and the planner's estimate.
The estimate is what `EXPLAIN` reports: `pg_class.reltuples` from the last
`ANALYZE` or autovacuum, scaled to the table's current size. A plan that
reports no estimate is refused the same way, since nothing measured the table.
Manual SQL is
classified by the same patterns: the forms VibORM generates and their common
manual spellings. A table the same migration creates first, as a force reset
does, is empty and never refused. `apply({ dryRun: true })` previews without
reading the estimate, and `reset` and `resolve` do not run this check.

Run a refused change outside the request, from a job whose client raises the
limit, or sets it to 0 for no limit:

```ts
const migrations = createMigrationClient(client, {
  storage,
  limits: { largeTableRows: 0, statementTimeout: 0 },
});
await migrations.apply();
```

The limit is PostgreSQL's. MySQL and SQLite apply such changes without this
check: SQLite has no row estimate unless `ANALYZE` has run, and counting rows
would scan the table it protects.

### Indexes and foreign keys as steps

On PostgreSQL, `generate({ lowLock: true })` (`viborm migrate generate
--low-lock`) builds each index on, and adds
each foreign key to, a table the migration does not create without a lock that
blocks writes while it reads the table. It publishes the change as consecutive
states, each with a commit of its own:

1. the rest of the change, in one transaction, as before;
2. each index, built with `CREATE [UNIQUE] INDEX CONCURRENTLY` outside any
   transaction;
3. the foreign keys, added `NOT VALID`: PostgreSQL checks new rows and scans
   nothing;
4. a last state that validates them with `VALIDATE CONSTRAINT`, whose scan
   blocks no write.

The last state carries the name you gave; the others are named
`<name> (step i of n)`. `apply` runs them as one path, `down({ steps: 1 })`
steps back one of them, and undoing the validation changes nothing. No step is
refused for the table's size, and the `V11009` refusal of a foreign key's
validation names this form.

It is opt-in: `generate` cannot see the database, so it cannot tell a large
table from an empty one, and a step outside a transaction needs the direct
session that `apply` takes for stepwise work, which a transaction pooler
cannot give (see [PostgreSQL](/docs/migration/drivers/postgresql#guarantees-and-limits)). Without
it, `generate` publishes one transactional state, as before.

An interrupted step leaves something `apply` or `resolve` settles:

- A failed or interrupted index build leaves one unfinished attempt and an
  INVALID index ([see above](#interrupted-create-index-concurrently)).
  `resolve({ outcome: "rolled-back" })` drops the index and `apply()` builds it
  again; `resolve({ outcome: "complete" })` rebuilds it in place.
- A failed validation (rows the key refuses, a time limit) rolls back alone,
  records a `failed` event, and leaves the marker at the state that added the
  key `NOT VALID`. Fix the rows and run `apply()` again.
- `generate` seals every state before it publishes the first, so a refusal
  publishes nothing. Only storage that fails between two manifests leaves the
  states before in storage, each a complete state. Run the same `generate`
  again with `from` set to the state it started from: the published states have
  the same ids, and the missing ones follow. Without `from` it continues from
  the last one, except after the keys' state, whose schema is already the
  target's: that call is a `noop`, and only `from` publishes the validation.

The build runs without the session's time limits; the validation runs under
`limits.statementTimeout` (10 minutes by default), which a very large table
may need raised.

Only the forward direction has the step form. Rolling a step back uses the
blocking forms: `down` drops a concurrently built index with a plain `DROP
INDEX`, and restores an index a step dropped with a plain `CREATE INDEX`. An
index redefined under the same name is dropped one state before it is built
again, so a unique index enforces nothing between those two commits, and a
duplicate written then makes the build fail and leaves an INVALID index. Give
the new definition a new name, or generate that change without `lowLock`.

The other changes listed above have no step form and stay refused: a type
change rewrites the table and a volatile default fills every row. `SET NOT
NULL` scans the table, which PostgreSQL 12+ skips behind a validated `CHECK
(column IS NOT NULL)`; VibORM does not generate that form, because its
snapshot does not record CHECK constraints: nothing would prove the check is
there between the steps, and undoing the last step would leave a check whose
validation must scan again. A manual transition can add the check `NOT VALID`
and validate it in states of its own; the `SET NOT NULL` that follows reads no
rows, but `largeTableRows` cannot tell, so run that last state from a client
that raises the limit. A key or check that manual SQL or `push` validates in
place is refused the same way.

A change is not split, and `generate` returns a warning saying so, when it
merges several parents, or when something other than an index build, an index
drop or a foreign key follows its first build (an enum drop, for one). `push`
has no history to split a change into. A unique constraint (`.unique()` on a
field) is still added with `ADD CONSTRAINT … UNIQUE`, which blocks writes while
its index builds; an index declared with `.index([...], { unique: true })` is
built concurrently.

## Expand / Contract Deployments

A migration tool does not provide zero-downtime deploys by itself. Use expand/contract:

1. **Expand** — add the new column, table, or index. Deploy application code that writes both shapes and reads the old one.
2. **Migrate data** — backfill with a manual transition that carries origin and destination checks.
3. **Contract** — deploy readers that only use the new shape, then generate a second state that drops the old objects.

Do not squash those states. Each published state stays in the graph so every environment can apply the exact transition it needs. Checkpoint a history only once every environment has applied it.

## Error Families

Automation should switch on stable families, not message text. CLI `--json` is a view of the same result. Exit codes derive from these families:

| Family | Typical meaning |
|--------|-----------------|
| Invalid estate / artifact | Hostile, truncated, or non-canonical bytes. |
| Ambiguous graph or path | Multiple leaves, names, prefixes, or routes. |
| Live drift | Managed schema does not match the marker snapshot. |
| Lock timeout | Another runner holds the target lock. |
| Marker conflict | Compare-and-swap lost. |
| Unfinished attempt | Ledger has an open attempt. |
| Consent required / mismatch | Push plan changed or destructive work lacks that preview's consent; generate found destructive changes that no resolver approved. |
| Unsupported provider | Effectful work is not admitted on this driver. |
| Partial effect | Stepwise progress is confirmed; later steps did not run. |
| Dispatch failed | `V11001`: the database refused a statement the migration dispatched; `meta` names the `step`, the states, `strategy`, `operationId`, `dispatchId`, `statementIndex` and the provider's code, and `cause` is the provider error. |
| Ambiguous commit | An opaque dispatch, or a COMMIT whose reply was lost, may have committed. |

```ts
import { isMigrationError } from "viborm/migrations";

try {
  await migrations.apply();
} catch (error) {
  if (isMigrationError(error)) {
    console.error(error.code, error.message);
  }
}
```

## CI/CD

```yaml title=".github/workflows/migrate.yml"
- name: Check estate
  run: npx viborm migrate check --json

- name: Apply
  run: npx viborm migrate apply --json
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

- name: Verify
  run: npx viborm migrate verify --json
```

```ts title="scripts/deploy.ts"
import { createMigrationClient } from "viborm/migrations";
import { createFsStorageWriter } from "viborm/migrations/storage/fs";
import { client } from "./db/client";

const migrations = createMigrationClient(client, {
  storage: createFsStorageWriter("./migrations"),
});

const status = await migrations.status();
if (status.unfinished) {
  throw new Error("Resolve the unfinished attempt before apply");
}
if (status.pending.length > 0) {
  await migrations.apply();
}
```

## Upgrading from 1.1.0

Upgrade every machine and CI job that runs migration commands against a
database, or reads its history, together. VibORM 1.1.0 reads every control row
and every history file strictly, and refuses three things 1.2.0 can write:

- **A destructive state's approvals** (see
  [Destructive changes need an approval](#destructive-changes-need-an-approval)).
  They are part of the state in the history, so keep 1.2.0 for a history that
  holds one.
- **The marker's `predicates` record** (PostgreSQL). An `apply` that reaches a
  state with partial indexes stores their predicates beside the marker (see
  [Apply](#apply)). 1.1.0 then refuses the marker with `V11012` ("migration
  marker has unknown key predicates"). Before running 1.1.0 against that
  database, remove the record:

  ```sql
  UPDATE "<schema>"."_viborm_migration_state" SET payload = (payload::jsonb - 'predicates')::text WHERE singleton = 1;
  ```

  1.2.0 still answers a no-op on that database, through the locked proof
  (about 30 statements), until its next `apply` reaches a state.
- **A `reanchored` ledger event**, written by `reanchor()` (see
  [History Older Than the Database](#history-older-than-the-database)). 1.1.0
  reads the whole ledger and refuses that database with `V11012` ("ledger event
  .kind is not a V1 kind"). The re-anchored marker itself is one 1.1.0 reads: its
  path starts at a baseline boundary, as `baseline` writes it. To run 1.1.0
  against that database, delete the event, which also deletes the database's
  record of the re-anchor:

  ```sql
  DELETE FROM "<schema>"."_viborm_migration_log" WHERE kind = 'reanchored';
  ```

  On MySQL and SQLite, drop the `"<schema>".` qualifier (MySQL keeps it, with
  backticks, when the client sets a namespace).

`<schema>` is the client's namespace (`public` when it sets none). Rolled back
this way, 1.1.0 runs `status`, `verify` and `apply` against the database as 1.2.0 left
it, with the history 1.2.0 used.

## Next Steps

**[Push](/docs/migration/push)**

History-free live schema sync

**[Storage](/docs/migration/storage)**

Estate reader and writer contracts

**[Migration Drivers](/docs/migration/drivers)**

Dialect DDL, probes, and atomicity

**[Compared with Prisma and Drizzle](/docs/migration/comparison)**

History, integrity, recovery, and workflow differences

## CLI failures and cleanup

Every acquired client is disconnected before a failure is reported. A cleanup
failure remains attached to the primary failure rather than hiding it. Human
errors include the VibORM code. With `--json`, stderr carries
`{ "error": { ... }, "exitCode": ... }`; stdout is reserved for successful
results. Generic failures exit 1, other VibORM failures exit 2, and migration
code `V110NN` exits `10 + NN` (for example V11010 exits 20). Baseline and drift
errors include the differing tables, columns, or constraints.
