Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

Migrate

Authenticated state-graph migrations — review exact SQL, publish immutable estate states, and apply them with a marker and ledger

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 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.

# Default estate directory is ./migrations
npx viborm migrate generate --name add-users
npx viborm migrate apply
npx viborm migrate status --json
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:

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.

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
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.
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.

--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. 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.

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.

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.

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.

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.

npx viborm migrate check --json
npx viborm migrate list --json
npx viborm migrate show add-users --json
npx viborm migrate graph --json
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.”

npx viborm migrate status --json
npx viborm migrate verify --json
npx viborm migrate log --limit 20 --json
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() (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 }.

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
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.

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’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.
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
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
npx viborm migrate baseline --to add-users --json
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.

npx viborm migrate generate --name adopt-dependency --adopt dependency
npx viborm migrate apply
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()). 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.
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:

npx viborm migrate reanchor --json
npx viborm migrate reanchor --to add-users --json
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.
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.

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 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.

npx viborm migrate reset --dry-run --json
npx viborm migrate reset --confirm --to add-users
await migrations.reset({ dryRun: true });
await migrations.reset({ to: { name: "add-users" } });

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.

Push Does Not Create History

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 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.
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.
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.
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.
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:

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). 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). 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.
import { isMigrationError } from "viborm/migrations";

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

CI/CD

- 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
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). 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). 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:

    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). 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:

    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

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.

Was this page helpful?