stable

Schema migration vocabulary

Canonical terms for evolving a record schema across generations: Transform, Cutover, and Rollout — and which side of the vault ↔ lobby boundary owns each.

When you change the shape of your records — add a field, drop one, restructure — the data already stored has to be carried from the old shape to the new. In noy-db, an encrypted, offline-first document store, a single database instance is called a vault; each vault tracks a schema generation number that advances when its record shape changes. klum-db (@klum-db/lobby) is the companion control plane — the lobby — that manages a fleet of vaults. This page pins down the three canonical terms for that evolution and which side of the vault ↔ lobby boundary owns each, so every package and page in the family means the same thing by them.

The ladder

Three nested concepts. Compose them as one sentence:

A Rollout applies a Transform to a vault group by performing a Cutover on each member vault.

Transform — (noy-db)

A pure, deterministic function mapping one decrypted record from schema generation N → N+1. No I/O, no coordination, no cross-record or cross-vault awareness. The unit of change.

Lineage: the "T" in ETL; an Avro/Protobuf schema-evolution upgrade function; the body of a Rails/Flyway/Alembic migration.
Code: TransformFn / the transform passed to the coordinatedCutover strategy.
Owner: noy-db — it runs on decrypted records, so it's crypto-bound.

Cutover — (noy-db)

The coordinated, in-place transition of one vault from generation N → N+1: raise a drain fence → quiesce all live clients to a barrier (or time out) → apply the Transform → bump the vault's generation. Multi-client by construction; indivisible from the vault's write-queue and write-gate — while the fence is up, writes are refused.

Lineage: a "cutover" (the controlled switch); the live phase of an online schema change (gh-ost / pt-osc); quiesce / drain / fence / barrier from distributed systems.
Code: vault.runSchemaCutover(), driven by SchemaFenceController (the fence state machine: normal → draining → migrating → complete → normal).
Owner: noy-db — it's concurrency control for one vault, which cannot be split from that vault's write path.

Rollout — (klum-db)

The orchestration of a Cutover across a set of one-or-more vaults (a group / fleet): select the members behind the target generation, migrate them in controlled batches, record per-vault status, and emit lifecycle events. A shard that fails is recorded, not fatal — the run continues past it, and because already-migrated vaults are skipped, a re-run resumes exactly where the last one stopped. Coordinates across the vault boundary; delegates each vault's Cutover to that vault.

Lineage: a "rolling rollout / upgrade" (Kubernetes); fleet-wide migration; phased rollout.
Code: VaultGroup.rolloutSchema() (the fleet) / cutoverShard() (one shard) — in @klum-db/lobby.
Owner: klum-db — coordination across multiple vaults is the Lobby's job.

Strategy axis (orthogonal to the ladder)

How a Cutover/Rollout reshapes data is a separate dimension. In-place is the strategy noy-db implements today (the coordinatedCutover strategy); the other two rows classify where those industry approaches sit relative to the vault boundary:

Strategy	Industry term	What it does	Falls under
In-place	online schema change	Mutate the existing vault behind the fence (the implemented model)	Cutover → noy-db
Expand–Contract	Parallel Change (Fowler)	Add the new shape additively, dual-write / backfill, then drop the old — within a vault	Cutover (multi-step) → noy-db
Blue-Green	blue-green migration	New-schema vault, transform-copy across, flip clients, retire old	Rollout → klum-db (cross-vault by construction)

Boundary rule

Transform + Cutover = noy-db (one vault's data + concurrency control, indivisible from the write path). Rollout = klum-db (coordination across the vault boundary). "Schema migration" is the informal umbrella for the whole activity — not a precise rung; don't use it as a tier label.