Module builtin_schema_migration

Support for migrating the schemas of builtin storage collections.

If a version upgrade changes the schema of a builtin collection that’s made durable in persist, that persist shard’s schema must be migrated accordingly. The migration must happen in a way that’s compatible with 0dt upgrades: Read-only environments need to be able to read the collections with the new schema, without interfering with the leader environment’s continued use of the old schema.

Two migration mechanisms are provided:

• Mechanism::Evolution uses persist’s schema evolution support to evolve the persist shard’s schema in-place. Only works for backward-compatible changes.
• Mechanism::Replacement creates a new shard to serve the builtin collection in the new version. Works for all schema changes but discards existing data.

Which mechanism to use is selected through entries in the MIGRATIONS list. In general, the Evolution mechanism should be used when possible, as it avoids data loss.

For more context and details on the implementation, see doc/developer/design/20251015_builtin_schema_migration.md.

Modules

migration_shard 🔒

Types and persist codec impls for the migration shard used by the Replacement mechanism.

Structs

Migration 🔒

Context of a builtin schema migration.

MigrationResult 🔒

The result of a builtin schema migration.

MigrationStep 🔒

A migration required to upgrade past a specific version.

Object 🔒

The object of a migration.

Plan 🔒

A plan to migrate between two versions.

Enums

Mechanism 🔒

The mechanism to use to migrate the schema of a builtin collection.

Constants

MIGRATIONS 🔒

Builtin schema migrations required to upgrade to the current build version.

Functions

read_migration_shard 🔒

Read the migration shard at the given timestamp, returning all entries that match the given predicate.

run 🔒

Run builtin schema migrations.