Migrations Apply to Local Realms Only
Migrations only apply to realms that are not synced through Realm. Synced realms do not have schema versions and automatically migrate objects to the latest schema.
Synced realms only support non-breaking schema changes. Breaking changes require a client reset.
A schema version identifies the state of a realm schema at some point in time. Realm Database tracks the schema version of each realm and uses it to map the objects in each realm to the correct schema.
Schema versions are ascending integers that you can optionally include
in the realm configuration when you open a realm. If a client
application does not specify a version number when it opens a realm then
the realm defaults to version
Increment Versions Monotonically
Migrations must update a realm to a higher schema version. Realm Database will throw an error if a client application opens a realm with a schema version that is lower than the realm's current version or if the specified schema version is the same as the realm's current version but includes different object schemas.
A migration is a function that updates a realm and any objects it contains from one schema version to a newer version. Migrations give you the flexibility to change your object schemas over time to accommodate new features and refactors.
Whenever you open an existing realm with a schema version greater than the realm's current version, Realm runs a migration function that you define. The function has access to the realm's version number and incrementally updates objects in the realm to conform to the new schema.
Realm automatically migrates certain changes, such as new and deleted properties, but does not automatically set values for new properties unless the updated object schema specifies a default value. You can define additional logic in the migration function to further customize property values.
Learn How to Modify a Schema
To learn how to modify your app's Realm object schemas with the Node.js SDK, see Modify an Object Schema.