Skip to content

feat(core): version the store schema with a migration runner#50

Merged
RatulMaharaj merged 1 commit into
mainfrom
worktree-store-migrations
Jul 5, 2026
Merged

feat(core): version the store schema with a migration runner#50
RatulMaharaj merged 1 commit into
mainfrom
worktree-store-migrations

Conversation

@RatulMaharaj

@RatulMaharaj RatulMaharaj commented Jul 5, 2026

Copy link
Copy Markdown
Member

What

The store applied its schema with CREATE TABLE IF NOT EXISTS on every open. That works until the first release that changes an existing table: databases already sitting on a volume keep the old shape and the agent starts failing at insert time. This PR gives the store a schema version and a migration runner.

How

  • packages/core/store/migrations.ts holds an ordered, append-only list of migrations. The array position is the schema version, recorded in the database itself via PRAGMA user_version, so there is no extra journal table.
  • On open, the Store applies each pending migration inside its own transaction and bumps the version in the same transaction. A failed migration rolls back completely and the next open retries from the same point.
  • A database reporting a version newer than the build knows is refused with a clear error, so an older binary won't run against a schema it has never seen.
  • Migration 001 is the baseline schema including the memories table from Persistent agent memory #37, kept idempotent (IF NOT EXISTS) on purpose: databases created before versioning report version 0 with some or all tables already present, and replay it harmlessly on first open.

No new dependencies; the runner is ~40 lines on node:sqlite.

Testing

  • deno task ok passes (fmt, lint, check, 112 tests).
  • New tests cover: fresh database reaches latest version, re-open is a no-op, pending migrations apply in order, pre-versioning databases upgrade with data intact, a failed migration rolls back and keeps the version, and a newer database is refused.
  • Smoke-tested on disk: built a database file the way released v0.2.0 does, reopened it through the new Store, confirmed existing rows survive and the file gets stamped to version 1.

🤖 Generated with Claude Code

The store applied its schema with CREATE TABLE IF NOT EXISTS on every
open, so a change to an existing table would silently never reach
databases already sitting on a volume. The store now keeps an ordered,
append-only migration list and records the schema version in the SQLite
file via PRAGMA user_version: each pending migration runs in its own
transaction, a failure rolls back cleanly and retries on next open, and
a database written by a newer build is refused instead of opened.

Migration 001 is the existing schema, kept idempotent so databases
created before versioning replay it harmlessly on first open.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@RatulMaharaj RatulMaharaj force-pushed the worktree-store-migrations branch from 3167c7d to 05565f3 Compare July 5, 2026 20:56
@RatulMaharaj RatulMaharaj merged commit 0669ae7 into main Jul 5, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant