Migrations - Android SDK

On this page

  • Summary

A migration transforms an existing realm and its objects from its current Realm Schema version to a newer one. Application data models typically change over time to accommodate new requirements and features. Migrations give you the flexibility to automatically update your existing application data whenever a client application upgrades to a newer version.

A synced migration is a migration for a realm that automatically Syncs with another remote realm. Users do not need to add migration code when changing the schema, but if they modify any client model classes they must increase the schema version. Realm Database automatically handles new fields added on the server schema by ignoring them on the client until they are added to the client model classes.

Synced realms represent multiple end users and devices that will likely not all immediately update to the most recent version of an application. MongoDB Realm ensures that synced schema changes are backwards compatible, which means that client applications that have not updated to the most recent version can still sync with clients that are using the most recent version.

MongoDB Realm handles synced migrations using the following framework:

Change Type
Schema Version
MongoDB Realm ignores any schema version set by the client application.
Migration Function
MongoDB Realm throws an error if the realm configuration includes a local migration function.
MongoDB Realm automatically applies additive changes, such as a new class or class property.

MongoDB Realm does not delete removed fields from the database, but ignores them in future read operations. MongoDB Realm includes deleted properties in new objects with a default value that depends on whether or not the property was required:

  • MongoDB Realm sets the value of optional deleted properties to null.
  • MongoDB Realm sets the value of required deleted properties to the empty value of the property type (e.g. 0 for numeric fields, "" for string properties, etc.).

MongoDB Realm prevents modifications to an existing property other than delete operations. Modifications that synced realms do not support include:

  • Changing a property’s type but keeping the same name.
  • Changing an object type's primary key.
  • Changing a property from optional to required (or vice-versa).
  • A migration transforms an existing realm and its objects from its current schema version to a later one.
  • MongoDB Realm allows you to specify migration functions for local migrations, i.e. migrations where the realm is not synced with MongoDB Realm.
  • Adding a field to a client model class requires you to manually increase the schema version.
Give Feedback

On this page

  • Summary