Migrate
voltro migrate — apply the declared schema through the declarative differ (an alias of voltro db apply).
voltro migrate applies your declared schema (*.entity.ts / *.schema.ts / schema.ts) to the configured database. It is an alias of voltro db apply: it diffs the declared schema against the live database and emits the ALTERs, so a changed column or a new index actually lands.
Before 0.11.4 this command was a create-only apply (
CREATE TABLE IF NOT EXISTS, no diffing), which meant a column or type change reported success having applied nothing. If you need that bootstrap-only behaviour for a brand-new database, it is nowvoltro migrate --create-only.
voltro migrate # apply the discovered schema to the configured store
voltro migrate apps/api # explicit app directory (defaults to cwd)voltro migrate forwards its arguments to voltro db apply, so the same flags apply — including its refusal under NODE_ENV=production, where the deploy step is voltro db deploy .; --create-only selects the bootstrap-only emitter instead. The diff / plan / apply / drift / squash workflow lives under voltro db (see below).
--create-only creates the SAME set of tables every other command declares: your
entities, the feature-mix framework tables, the agent-thread tables when the app
has an *.agent.tsx, and every plugin's extendSchema.tables — plus each
plugin's extendSchema.migrations afterwards. Before 0.34.0 it assembled that
set itself and got the last two wrong, so bootstrapping a fresh database the
documented way produced one with no plugin tables at all.
For the deep dive on the schema DSL + day-to-day patterns, see Database / Migrations.
How discovery works
The migrator walks the project root (skipping node_modules, dist, .framework, etc.) for:
*.entity.ts/*.schema.ts/schema.ts— your table descriptors.- Feature files (
*.workflow.tsx,*.cron.tsx,*.webhook.tsx) — their presence decides which framework-internal_voltro_*tables get created (workflow-run tables, schedule ledgers, etc.)._voltro_tracesis the exception — env-gated, not feature-gated: it's created undervoltro dev(durable trace history on by default) but NOT undervoltro serve/voltro start(prod default off → setVOLTRO_TRACING_PERSIST=interestingto opt in). See Distributed tracing.
The core actors table is injected automatically when you didn't declare your own, and tenants is registered when present, so the audit / soft-delete / tenant mixins resolve their FK targets.
voltro dev already auto-migrates
On a SQL-backed store, voltro dev AUTO-APPLIES the discovered schema before any handler boots — so a standalone voltro migrate is rarely needed in the inner loop. It's the CI / ops-pipeline entry point.
Opt out of the dev auto-migrate when you ship schema through a separate reviewed pipeline:
VOLTRO_AUTO_MIGRATE=0 voltro dev .The boot log then says auto-migrate: skipped (VOLTRO_AUTO_MIGRATE=0), and you run voltro migrate (or voltro db apply) explicitly.
Store + dialect selection
The dialect is resolved from DB_DIALECT (default postgres); the connection comes from DB_URL / DB_PRIMARY_URL, falling back to the discrete DB_* / PG_* fields (DB_HOST / PG_HOST, DB_PORT / PG_PORT, etc.).
DB_DIALECT=postgres DB_URL=postgres://app:app@localhost:5432/app voltro migrateOn MySQL / MariaDB, voltro db plan also reads the store's declared character set (store: { dialect, charset } in app.config.ts) and plans a convert-charset rewrite for any table stored otherwise; without a declaration it prints the tables whose text columns cannot hold what their json columns can. See MariaDB → Character set.
Migrating against DB_DIALECT=memory is rejected — there's nothing to migrate. In dev with the memory store, the in-memory store learns its shape from the schema declaration directly; switch to a SQL dialect (postgres, sqlite, mysql, mariadb, mssql, turso) to test the real migration path.
The declarative diff workflow — voltro db
The plan / apply / drift / squash machinery — diffing the declared schema against a live database, generating reviewable DDL, applying a pre-reviewed plan in production — lives under voltro db:
voltro db plan # diff declared schema vs live, color-coded
voltro db plan --json # machine-readable for CI / PR comments
voltro db plan --check # CI gate: exit 1 when ANY operation is pending
voltro db plan --sql # raw DDL preview
voltro db plan --against <url> # diff vs a REMOTE env via /_voltro/inspect/migrations
voltro db apply # execute the plan (refuses NODE_ENV=production — and an UNSET NODE_ENV resolves to production)
voltro db apply --yes # answer the question a per-statement dialect asks before it starts (a pipeline cannot)
voltro db apply --forget-deploy <id> # after repairing by hand: forget a deploy whose undo could not complete
voltro db apply --plan plan.json # prod: apply a pre-reviewed plan from CI/CD
voltro db plans [--limit 20] # plan history from _voltro_migration_plans
voltro db branch --pr <n> # REHEARSE the plan on a throwaway branch of the live schema
voltro db drift # alert if live diverged from the latest applied fingerprint
voltro db squash --before <iso-date> # consolidate history into one snapshot
voltro db restore-snapshot <plan-id> # restore soft-dropped columns from a planEvery
voltro db …/voltro migrateinvocation declares its environment. An unsetNODE_ENVresolves toproductionfor these commands — the same way it does forvoltro serveandvoltro start— so a barevoltro db applywith noNODE_ENVrefuses (exit 3) rather than applying an un-reviewed diff. Locally:NODE_ENV=development voltro db apply, or putNODE_ENV=developmentin your.env(a declared value always wins).voltro devdeclaresdevelopmentfor itself and needs nothing.The second reason it matters is not the refusal:
_voltro_tracesand_voltro_undo_logare created only outside production, so a migration command that resolved the environment differently from the serving process declared a different schema — and the declared set is what the fingerprint hashes.
The two fingerprints under a plan
db plan prints two hashes — live and declared (fingerprintLive /
fingerprintDeclared in the JSON record). Both are hashed over the same
canonical form — the planner's own equivalence (restrict and noAction, now
and the engine's spelling of it, a boolean and its 0/1, the width the
emitter renders for a oneOf text) — so on a database the planner has
converged on they agree. They part only on a table the diff never compares:
cluster_*, an undeclared _voltro_*, a soft-drop snapshot, a name in
VOLTRO_DB_IGNORE_TABLES. The record carries fingerprintDivergence: { outsideDiff, diffEquivalent }, both lists of table names, and the TTY prints
them under an empty plan whenever they are not empty. A name under
diffEquivalent is a detail the planner calls equal that the fingerprint does
not yet — report it; it is a gap in the shared rules, not in your schema. voltro serve is not involved: its boot check compares the
declared fingerprint against the one the last voltro db apply recorded, never
the live hash.
The production deploy step runs the file migrations and the plan together:
voltro db deploy . --yes # before-schema files → plan → apply → after-schema files, allowed under NODE_ENV=productionA separate file-based migration surface (the offline escape hatch) lives alongside it:
voltro db files # apply pending migrations/<id>.ts files — after-schema ones only once the plan is empty
voltro db files --phase before-schema # one pass: before-schema | after-schema
voltro db migrate # apply pending defineMigration *.migration.ts steps
voltro db rollback [--to <id>] # undo *.migration.ts steps
voltro db status # list applied / pending migrations of both kinds
voltro db seed # run boot-lifecycle seeds against the configured store
voltro db seed --id <name> # run one seed by id
voltro db seed --store memory # explicit override; default = the app's configured storevoltro db seed defaults to the same store the app runs on (DB_DIALECT → STORE → app.config.ts store: → postgres) — seeding to memory was a silent data-loss footgun, so you opt into it explicitly.
Production safety
For production deploys:
- Always apply schema BEFORE app version bumps. App N+1 expects schema N+1; app N should still tolerate schema N+1.
- Deploy with one step, or review the plan first.
voltro db deploy . --yesin the migrate job runs the before-schema files, the plan (printed and recorded), the apply and the after-schema files. To apply a plan reviewed earlier instead:voltro db files . --phase before-schema, thenvoltro db plan --json > plan.json, thenvoltro db apply --plan plan.json. - Check for drift.
voltro db driftflags a live database that diverged from the last applied fingerprint. - Verify backups before destructive changes. Restoring is the actually-tested rollback path.
- A deploy is all-or-nothing, on every dialect. On Postgres and SQL Server
voltro db applyruns every pending file migration and the whole schema plan as a single transaction: a failure anywhere — a throwing backfill, a refused plan, a broken migration — rolls back everything, including the rows an earlier migration of the same run wrote and the ledger rows that would have recorded them. The online operations Postgres refuses inside a transaction (CREATE INDEX CONCURRENTLY) follow after the commit, on their own. MySQL, MariaDB, SQLite and Turso cannot hold DDL in a transaction, so there the runner undoes instead of rolling back: it snapshots the schema before the run, and when a step fails it runs thedownof every file migration this run applied, newest first, plans the schema back to the snapshot (a rename this run applied is renamed back, not dropped and re-added), converts every table this run converted to a declared character set back to the one it had, and clears the resume ledger. The report lists what was undone, what stays because itsdownisirreversible(), and what came back empty because this run had dropped it. "The database is as it was" is printed only after the schema, the file migrations and every string column's character set have been read back and compared; when something still differs, the report lists each difference instead. The undo survives the process too: the baseline is written to_voltro_deploysbefore the first statement and the row deleted when the deploy finishes, so a deploy killed mid-way (an OOM-killed migrate job) is found by the next apply — which names it, undoes from its baseline, and only then does its own work. An undo that cannot complete leaves the row asfailedwith its report; every later apply refuses until--forget-deploy <id>says an operator repaired by hand.VOLTRO_DEPLOY_TRANSACTION=offswitches both off: per-statement application, nothing undone. - On MySQL, MariaDB, SQLite and Turso, the apply asks before it starts. A deploy there is undone rather than rolled back, and two things escape an undo: the rows a lossy operation removed, and a migration whose
downisirreversible(). Sovoltro db applyasks before the first statement — naming the pending file migrations and which of them are irreversible, and at plan time the counts (operations, rolling-deploy-unsafe, lossy) — then waits for ayat a terminal; a pipeline passes--yesto acknowledge it, and a non-interactive run without--yesis refused rather than answered for.--yesanswers only that question: it acknowledges no data loss — a lossy operation is authorised where it is declared (adropped()column, orVOLTRO_DESTRUCTIVE_OKfor a blocked drop; see Rename and drop), and a drop the schema does not declare stays blocked with or without it. Postgres and SQL Server roll back and are not asked. Within a plan, the backfills of non-batched three-step adds are gathered and run in one transaction of their own before the first drop, so the data half of a plan is atomic on every dialect even where the DDL half cannot be.
With VOLTRO_SOFT_DROP=1, the undo keeps the rows of an app table this run created by renaming it to a snapshot. On MySQL and MariaDB it removes that table's outgoing foreign keys first, so the retired table cannot block restoring an active parent's character set. Added columns are retained as snapshots too; only columns present before the run are compared when verifying the restored character sets. Framework tables created by the failed run are removed before the character-set undo.
If the undo stops part-way, revertedOperations lists every schema operation already completed, including a foreign key removed before a later table rename failed. It does not list the operation that failed. Use those labels and the named failing statement to determine which changes still need repair; the database is not reported as restored.
For zero-downtime deploys with breaking schema changes:
- Add new columns / tables → apply first, then deploy.
- Remove columns → deploy code that doesn't read them, then apply the drop.
- Rename → add new column + dual-write, deploy, drop old column later.
The framework doesn't enforce these — that's an SRE responsibility. See Migrations for the playbook.
Rehearsing a migration before it reaches production — voltro db branch
voltro db plan tells you what the diff IS. voltro db branch tells you what it
DOES: it branches the live schema into a throwaway namespace, applies the plan
there (destructive operations included — the branch is disposable, so the
operation most likely to fail is the one that actually gets rehearsed), re-plans
to prove the migration converges, and drops the branch.
voltro db branch --pr 128 --json > rehearsal.json # exit 2 = the plan destroys dataPostgres only, and it says so on the other dialects rather than emitting Postgres
syntax at them. Full behaviour, exit codes and the --seed trade-off:
Data branching.
See also
- Database / Migrations — the schema DSL deep dive
- Data branching —
voltro db branch+ the branch primitive - Self-hosting — production migration patterns