Skip to main content

​
Migrations

​
Operations · Migrations

Operational objective — Change persisted state while old and new application versions may coexist.
Expand-migrate-contract plans, backfills, compatibility windows, and rollback boundaries.

​
Key concepts

Compatibility

Old plus new

Backfill

Bounded batches

Rollback

State-aware

​
Operational surface

​
Evidence over assumption

Treat data deletion and irreversible transformations as high-impact operations with a separate recovery decision.

​
Operational context

A schema change is deployed across time; code, workers, replicas, and operators do not switch versions simultaneously.
Operator’s principle The safest migration is a sequence of compatible states, not one clever statement.

​
Implementation notes

​
Decision lens

​
Jeston migration runner

Jeston 2.0.0 includes a provider-neutral createMigrationRunner contract. Migration files use deterministic names such as 0001_users.up.sql and 0001_users.down.sql.
The runner records a SHA-256 checksum for every applied migration, executes each migration through the SQL client’s transaction contract, reports pending files, and refuses to continue when an applied migration is edited in place. Change an already-applied migration by creating a new migration instead.

​
References

Last modified on September 10, 2026