6.7.1 Components ¶

Migration interface

A single apply(Connection db) method, plus version() (target version) and name() (for logs).

MigrationRegistry

A static ordered list of Migration instances plus CURRENT_DB_VERSION. The two must stay in lockstep; the framework fails fast at startup otherwise.

DbMigrator

Runs at MCPServer.<clinit> via runOnStartup(). Creates a db_version bookkeeping table on first run, finds the gap between the database’s current version and CURRENT_DB_VERSION, applies each missing migration in a separate transaction, recording the new version after each success.

Migration002AddRecordVersion, ...

One class per applied change. Once shipped, a migration is permanent — never edit a deployed one; write a new migration that fixes or supersedes it.

6.7.2 Invariants ¶

• Migrations are additive. Add columns, indexes, nullable fields. Never DROP, RENAME, or rewrite existing data. The narrow exception is the embedding-dim change (see Embedding Migration), which clears derived data that the walker immediately rebuilds.
• Version 1 is the baseline established by sql/001_init.sql. The first Migration class is at version 2.
• Each migration runs in its own transaction. Failure rolls that migration back; db_version stays at the prior value; next startup retries.
• Refuses to start if the database’s version is higher than the code expects (rollback scenario). Restore from backup or upgrade the code.