Schema Versions & Migrations - React Native SDK

Migrations Apply to Local Realms Only

Migrations only apply to realms that are not synced through MongoDB Realm. Synced realms do not have schema versions and automatically migrate objects to the latest schema.

Synced realms only support additive schema changes. Destructive 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 0.

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.

MongoDB 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 React Native SDK, see Modify an Object Schema.

Give Feedback