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, andapplyhave stable--jsonoutput - 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 --jsonimport { 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-lossconst 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 publishedGenerate 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
upvalue is one opaque provider dispatch — VibORM does not split it on semicolons. rollbackis{ kind: "manual", execution, sql }or{ kind: "irreversible", reason }. There is noautomaticinput arm.- Stepwise manual work without complete origin and destination checks is refused before dispatch.
- A requested
transactionalboundary 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 --jsonconst 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 --jsonconst 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 --jsonconst 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 --jsonawait 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 --jsonawait 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 applyconst 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, anON CONFLICTclause (on the key, a NOT NULL or a UNIQUE:REPLACEwould overwrite a row a create should refuse), or a column collation other thanBINARY. A CHECK constraint is refused by every SQLite command already (V11009), as is a non-BINARYcollation on a key or index column (V8001). - on PostgreSQL: a trigger, a rule, row-level security (enabled or forced),
UNLOGGEDstorage, a CHECK constraint, aDEFERRABLEkey, or a column collation other than its type’s default (the declaration writes noCOLLATE, 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’sCREATE TABLEwrites (a table made with the database defaultutf8mb4_0900_ai_cicompares 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
applyruns 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().markerStateis"ahead"or"unknown", andapplyrefuses withV11002.
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 --jsonconst { 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 (
applyandverifyhandle it), or there is no marker (usebaseline).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.
- 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.
- Prune into a fresh history.
prunecopies 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 nothingcheck()would report as an orphan. - Switch to the fresh history and re-anchor each database. Its marker
names a state the fresh history does not hold (
status().markerStateis"unknown", andapplyrefuses withV11002).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:
reanchorrefuses withV11014. Apply it with the old history first, whichpruneleft untouched, then re-anchor. Where its data can go,resetclears it and replays the fresh history instead. - Resolve unfinished attempts.
reanchorrefuses while one is open, andresolveneeds the states the attempt names. - Generate after the checkpoint from it. Between the checkpoint and the
switch, the old history has two leaves, so
applyneeds{ to }andgenerate()withoutfrommerges both leaves. A state that merges older history keeps it:prunecopies 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-usersawait 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 KEYorCHECKconstraint added withoutNOT 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:
- the rest of the change, in one transaction, as before;
- each index, built with
CREATE [UNIQUE] INDEX CONCURRENTLYoutside any transaction; - the foreign keys, added
NOT VALID: PostgreSQL checks new rows and scans nothing; - 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 andapply()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
failedevent, and leaves the marker at the state that added the keyNOT VALID. Fix the rows and runapply()again. generateseals 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 samegenerateagain withfromset to the state it started from: the published states have the same ids, and the missing ones follow. Withoutfromit continues from the last one, except after the keys’ state, whose schema is already the target’s: that call is anoop, and onlyfrompublishes 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:
- Expand — add the new column, table, or index. Deploy application code that writes both shapes and reads the old one.
- Migrate data — backfill with a manual transition that carries origin and destination checks.
- 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
predicatesrecord (PostgreSQL). Anapplythat reaches a state with partial indexes stores their predicates beside the marker (see Apply). 1.1.0 then refuses the marker withV11012(“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
applyreaches a state. -
A
reanchoredledger event, written byreanchor()(see History Older Than the Database). 1.1.0 reads the whole ledger and refuses that database withV11012(“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, asbaselinewrites 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
Push
History-free live schema sync
Storage
Estate reader and writer contracts
Migration Drivers
Dialect DDL, probes, and atomicity
Compared with Prisma and Drizzle
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.