# Local Data Migrations

> Rules for changing Klex config schemas, SQLite schemas, persisted JSON, store metadata, local-data definitions, or migration and recovery code.

- Skill: `stagewise-io/local-data-migrations` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stagewise-io/local-data-migrations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stagewise-io/local-data-migrations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: stagewise-io (https://skillmd.com/u/stagewise-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stagewise-io/local-data-migrations

---


# Local data migrations

Read `apps/klex/src/local-data/architecture.md` before changing persistent state.

## Required workflow

1. Classify the change as one of:
   - No representation change.
   - Compatible additive change.
   - Schema migration.
   - Compatibility-floor increase.
2. Update the store definition in its owning module.
3. Confirm the definition remains present in `local-data-registry`.
4. Add old/current/newer fixtures and downgrade, failure, and recovery tests appropriate to the classification.
5. Run local-data tests, the owning module tests, typecheck, lint, executable build, and native smoke verification.

## Compatibility rules

- Migrations are forward-only. Never add a down migration.
- Increment `schemaVersion` for transformations and add contiguous single-version steps with input and output schemas.
- Increment `compatibilityVersion` when an older writer could discard or misinterpret new semantics without requiring a representation transformation.
- Set `minimumKlexVersion` to the first binary supporting the new schema or compatibility floor.
- Preserve unknown JSON fields at every evolvable object boundary. If that is unsafe, raise compatibility instead of silently stripping data.
- Prefer optional additions. Delay destructive SQLite column/table removal and JSON field removal across multiple release cycles.
- Keep preflight read-only across the entire registry before the first mutation.
- Treat checkpoints as disaster recovery, never as routine downgrade or divergent-history merging.
- Never migrate, regenerate, replace, or include `identity/private-key.pem` as structured data in a checkpoint.
- Do not fold Cloud API compatibility into local storage versions.