MigrationRunner

Executes an ordered chain of ConfigMigration steps to upgrade a raw YAML map from an older schema version to the current version.

The runner maintains a sorted list of migrations and applies them sequentially, starting from the file's detected version (read from the configVersion key, defaulting to 1) and ending at the target version.

Chaining algorithm:

1. Read configVersion from the raw map (defaults to 1 if absent).

2. If the file version is already at or above the target, return immediately.

3. Create a backup of the source file as <filename>.v<version>.bak (only once per version).

4. Find the migration where fromVersion == currentVersion, apply it, advance to toVersion.

5. Repeat step 4 until the target version is reached.

6. Set configVersion in the map to the target version.

If a gap exists in the migration chain (no migration for a given version), an IllegalStateException is thrown listing the available migrations.

Example:

val runner = MigrationRunner()
runner.register(MigrateV1ToV2)
runner.register(MigrateV2ToV3)

// Migrates from v1 -> v2 -> v3, creating config.yml.v1.bak
val upgraded = runner.migrate(rawMap, targetVersion = 3, sourceFile = configFile)

See also