Skip to content
Forgeplan

forgeplan migrate

forgeplan migrate runs pending schema migrations against the LanceDB tables in .forgeplan/lance/. Forgeplan occasionally adds columns or changes table structure between releases (e.g. v0.17 → v0.18 added columns for BM25 and Russian morphology). migrate applies those changes in-place, preserving all artifacts, links, and evidence, without forcing a destructive reinit.

When to use

Section titled “When to use”
  • Immediately after upgrading the Forgeplan binary (cargo install forgeplan, brew upgrade forgeplan, or a release download).
  • When forgeplan health or any other command reports schema version mismatch or “missing column” errors.
  • Before resuming work in a workspace that was last touched under an older version.

When NOT to use

Section titled “When NOT to use”
  • On a brand-new workspace created by the current binary — there is nothing to migrate.
  • As a substitute for rebuilding the search index — migrations change schema, not content. For index rebuilds use forgeplan scan-import.
  • As a recovery tool for corrupted workspaces — migrations assume the LanceDB files are structurally valid. For corruption, restore from forgeplan export backup.

Usage

Section titled “Usage”
forgeplan migrate

Options

Section titled “Options”
  -h, --help     Print help
  -V, --version  Print version

Examples

Section titled “Examples”

Example 1: Post-upgrade migration

Section titled “Example 1: Post-upgrade migration”
Terminal window
cargo install forgeplan        # upgrade to new version
forgeplan migrate              # apply any pending schema changes
forgeplan health               # verify workspace is clean

The standard post-upgrade sequence. migrate is a no-op if nothing changed, so it’s safe to run unconditionally after every upgrade.

Example 2: Fixing “missing column” errors

Section titled “Example 2: Fixing “missing column” errors”
Terminal window
forgeplan list
# Error: column 'bm25_tokens' not found
forgeplan migrate
forgeplan list
# OK

If a command fails with a schema-level error, migrate is usually the one-step fix.

Example 3: Safe rollback path (if migrate is not enough)

Section titled “Example 3: Safe rollback path (if migrate is not enough)”
Terminal window
forgeplan export --output pre-migrate-backup.json
cp -r .forgeplan .forgeplan-backup-$(date +%Y%m%d)
forgeplan migrate
# if something goes wrong:
rm -rf .forgeplan
forgeplan init -y
forgeplan import pre-migrate-backup.json

Always back up before running migrations against production workspaces with meaningful artifact history.

How it fits the workflow

Section titled “How it fits the workflow”

migrate is part of the upgrade path, not the daily artifact loop. A typical version bump goes:

  1. forgeplan export --output pre-upgrade.json — safety backup
  2. Upgrade the binary (cargo install / brew upgrade)
  3. forgeplan migrate — apply pending schema changes
  4. forgeplan health — verify the workspace is clean
  5. Resume normal work (forgeplan new, forgeplan validate, etc.)

If migrate is insufficient (e.g. a breaking schema change), fall back to the export + reinit + import cycle documented in forgeplan init.

Safety notes

Section titled “Safety notes”
  • Always export before migrating production workspaces. migrate is designed to be non-destructive, but new binaries can have bugs. forgeplan export is cheap and fast; run it first.
  • migrate is idempotent. Running it twice in a row is safe — the second run detects no pending migrations.
  • .forgeplan/lance/ is gitignored — if migration leaves it in a weird state on one machine, rm -rf .forgeplan/lance && forgeplan scan-import will rebuild the index from tracked markdown.
  • Schema version is tied to the binary. Don’t mix binaries of different versions against the same workspace without running migrate in between.

See also

Section titled “See also”