forgedb migrate
Record, build, and run schema migrations that rewrite data-at-rest across format versions.
Schema evolution follows the generate-then-compile model: edit schema.forge, regenerate,
rebuild. Additive changes (a new model, a new nullable field) survive automatically on
reopen. Everything else rewrites data-at-rest, and forgedb migrate drives that through a
generated offline transformer. The migrations feature guide
has the full workflow.
Subcommands#
| Command | Purpose |
|---|---|
create <description> | Record a migration; with --auto, diff the schema and classify/scaffold the change. |
status | Show migration status. |
build --from F --to T | Generate + compile the offline transformer bin for a version range. |
run --src S --dest D | Run a built transformer over a source → destination data directory. |
up | One-CLI migration: build the transformer + run it over a data dir (or every tenant). |
create#
forgedb migrate create <description> [--auto] [--schema <PATH>]| Flag | Type / default | Meaning |
|---|---|---|
<description> | string (required) | Human description of the migration. |
-a, --auto | bool (false) | Auto-detect schema changes by diffing against the recorded snapshot; record, classify (Auto/Authored), and scaffold any authored body. |
-s, --schema <PATH> | path | Schema file to diff against the snapshot (for --auto). |
status#
forgedb migrate statusShow applied and pending migrations. Takes no flags.
build#
forgedb migrate build --from <F> --to <T> [--output <DIR>]| Flag | Type / default | Meaning |
|---|---|---|
--from <F> | u32 (required) | Origin (current on-disk) format version. |
--to <T> | u32 (required) | Destination format version. |
-o, --output <DIR> | path (migrations/transform) | Where to emit + build the transformer crate. |
run#
forgedb migrate run --src <DATA> --dest <MIGRATED> [--bin-dir <DIR>]| Flag | Type / default | Meaning |
|---|---|---|
--src <DATA> | path (required) | Source data directory at the origin format version. |
--dest <MIGRATED> | path (required) | Destination directory to materialize (must be absent/empty). |
--bin-dir <DIR> | path (migrations/transform) | The built transformer crate directory. |
up#
forgedb migrate up [--from F] [--to T] [--src S --dest D] [--tenant-root R] [--output O] [--dest-suffix SUF]| Flag | Type / default | Meaning |
|---|---|---|
--from <F> | u32 (detected from source manifests) | Origin format version. |
--to <T> | u32 (lineage's current version) | Destination format version. |
--src <S> | path | Source data directory (single-dir mode). |
--dest <D> | path | Destination directory to materialize (single-dir mode). |
-o, --output <O> | path (migrations/transform) | Transformer crate directory. |
--tenant-root <R> | path | Migrate every data dir directly under this root (per-tenant sweep). |
--dest-suffix <SUF> | string (-migrated-v<to>) | Per-tenant destination suffix. |
up writes a fresh destination
migrate up builds the transformer, cargo builds it, and runs it, writing a fresh
destination and leaving the source untouched, so the original is your rollback. The app must
be stopped (offline / exclusive-writer). build, run, and generate transform are the
lower-level primitives up composes.
Examples#
Record an additive change and regenerate:
forgedb migrate create "add note field" --auto --schema schema.forge
forgedb generateMigrate one data directory in a single step:
forgedb migrate up --from 1 --to 2 --src ./data --dest ./data-migratedSweep every tenant under a root:
forgedb migrate up --tenant-root ./tenants --to 2