migrate-data

Migrate Data

Phase 3 of the migration pipeline: move a live OpenFGA store's relationship data into a live SpiceDB instance -- extract, transform, load, and verify -- and emit the ID codec module that this phase and phase 4 (client code) must encode identically through. Phase 4 is /spicedb-dev:migrate-code, which imports this exact codec module rather than inlining its own encode/decode logic -- say so, and name it, rather than treating the rewrite as manual.

This is the most consequential command in the pipeline. /spicedb-dev:migrate-schema and /spicedb-dev:migrate-tests produce files a human reviews before anything happens to a live system. This command writes to a live SpiceDB instance. A mistake here is expensive and hard to undo, and two mistakes are common enough to name up front:

• A relation split's write target is the __direct relation, never the permission. SpiceDB rejects a write to a permission outright, so getting this backward halts loudly on the first write -- but only if every write actually goes through this rewrite. A store with even one split relation depends on it (see data-mapping.md, "Tuples are writes").
• Running converted client code before this phase completes denies everything. This is the plugin's existing "data before code" rule (migrating-to-spicedb/SKILL.md): a check against a SpiceDB instance still missing relationships fails closed, silently, for every request touching unmigrated data. Do not treat this command as optional groundwork phase 4 can route around.

This command's job is to convert, following the pack's data-mapping reference exactly, and to decide as little as possible about how -- every rewrite rule is "look this up in migration-map.json," not a judgment call. What it does not minimize is caution around the write itself: dry run before load, TOUCH not CREATE, detect a partial prior attempt before choosing a load strategy, and a verification pass that actually re-reads the target and can fail.

This command has no gate of its own, reduced or otherwise. Like /spicedb-dev:migrate-tests, it is a pure consumer of migration-map.json and migration-plan.md -- every naming and encoding decision below is a lookup against the JSON, not something this command could decide standalone; migration-plan.md supplies only the narrative sections (Source, Target) that have no JSON counterpart. If migration-map.json is missing, or its phase_status["0"] shows it was authored by the reduced inline gate rather than the full one, this command halts and routes to /spicedb-dev:migrate rather than inventing a gate to fill the gap.

Outputs, written to [output-dir] (default: the directory phase 0 wrote migration-map.json to, i.e. the project being migrated -- not the shell's current working directory) unless step 3 places the code elsewhere in the project:

• migration/id_codec.<ext> -- the ID codec module, in the project's language.
• migration/migrate_data.<ext> -- the extract/transform/load script, in the project's language, importing the codec rather than inlining encoding logic.
• migration/relationships.jsonl -- the transformed relationship-write set, one JSON object per line, written by the script itself and read back by its own --verify pass.
• migration/checkpoint.json -- extraction and load progress, written and read by the script for resumability.
• migration-map.json -- updated in place: phase_status["3"], and an entry appended to decisions.additional if the project language was ambiguous enough to ask about (step 3).
• migration-plan.md -- regenerated in place: the rendered sections from the updated migration-map.json, plus the narrative Sync obligations section revised per its own rule (step 8).