Configuration migration
Use migrations when an app update renames or moves configuration keys or changes how values are represented. Declare the changes in the schema and Settings applies them at launch, reducing the need for people to move their settings manually.
Versions and operations
schema_version = 2
migration_version_key = "schema_version"
[[migration]]
version = 2
[[migration.rename]]
from = "display.font_size"
to = "general.font_size"
[[migration.delete]]
key = "display.tick_rate"
[[migration.transform]]
from = "mode"
to = "vivarium.enabled"
type = "enum_to_bool"
match = "vivarium"This is a schema fragment. Add it to the same schema as your [[tabs]] and other definitions.
| Field | Meaning |
|---|---|
schema_version | Target configuration version. Omitting it disables migration |
migration_version_key | Configuration key recording the applied version. Defaults to schema_version |
version in [[migration]] | Version applied by this step. Must be unique and no higher than the target |
[[migration.rename]] | Move the value from from to to, including renames within a table |
[[migration.delete]] | Delete key |
[[migration.transform]] | Move and convert. type is "rename" or "enum_to_bool" |
match | Required for enum_to_bool. Produces true when the source value matches this string, otherwise false |
What happens at launch
A missing recorded version is treated as 0. Settings applies steps above the recorded version and no higher than the target, in ascending version order. It then records the target version and saves the file. If the file is already at or above the target, nothing happens.
A move or conversion with a missing source does nothing. If a destination already exists, its value is preserved and the move is skipped. Empty parent tables are removed. Within each migration, operations run in the order rename, transform, then delete.
Migrations run and save before the settings window appears. Clicking Cancel during ordinary editing on Windows or Linux does not undo a migration already performed at launch.
Validate and try a migration
Use settings-schema-checker to check for duplicate versions, versions above the target, missing match for enum_to_bool, and related errors.
To test the actual result, make a copy of an old-format config.toml. Launch Settings with that copy's path and check the resulting keys, values, and recorded version. Migration definitions are embedded in the schema, so rebuild after changing them.