Skip to main content
Version: MVP

Local store migrations

3 min readFor operators & maintainersUpdated 2026-05-19

What you'll do

Understand how Craik's local-state migrations run, where versions are tracked, how compatibility fixtures keep older stores on a path forward, and what to do when a migration fails.

Forward-only, never silent.

Migrations run during LocalStore.initialize(). Craik never silently recreates an unreadable local store — receipts, handoffs, memory proposals, case files, and task runs may be needed for audit or recovery.

Version tracking​

Where
Records
Notes
SQLite PRAGMA user_version
current
The current migration number.
migrations table
history
One row per applied migration.
local_store_metadata
metadata
Created by migration 2 · updated by later framework migrations · records current store schema version and the contract registry count visible to the installed Craik build.

Migration runner​

Craik applies local-store migrations through a registered, forward-only runner. Each migration has an integer version, a stable name, and one function that mutates SQLite state. The registry must be contiguous from version 1 to the current supported migration; gaps fail at import time rather than leaving operators with an ambiguous upgrade path.

The v0.2 migration framework keeps the existing v1 and v2 behavior and adds migration 3 as an example metadata migration. Migration 3 records that the store was upgraded through the registered migration framework.

Compatibility fixtures​

Migration compatibility tests load prior schema fixtures from tests/fixtures/local_store/. The v1 fixture describes the first records-based store layout and is migrated to the current schema during tests. This keeps old local stores on an explicit compatibility path instead of depending only on fresh database initialization.

Failure handling​

If a migration fails, Craik raises a local-store migration error with recovery guidance.

  1. Back up state/craik.sqlite3.
  2. Keep the original file unchanged.
  3. Run craik doctor for diagnostics.
  4. If the database version is newer than the installed Craik build supports, upgrade Craik before opening the store.
  5. If a migration failed partway through, restore the backup or copy the database aside before retrying.

What's next​

GuideDoctor diagnosticsThe first command to run when a migration fails.ReferenceLocal storeThe persistence-layer reference.GuideUpdating CraikWhen to expect a migration during an upgrade.