Migrating Your iOS App's Realm Schema in Production
Rate this tutorial
This is fine if these features don't require any changes to your data schema. But, that isn't always the case.
Fortunately, Realm has built-in functionality to make schema migration easier.
This tutorial will step you through updating an existing mobile app to add some new features that require changes to the schema. In particular, we'll look at the Realm migration code that ensures that no existing data is lost when the new app versions are rolled out to your production users.
The first new feature we've been asked to add is a flag to indicate whether each scrum is public or private:
Remember that our original version of Scrumdinger is already in production, and the embedded Realm database is storing instances of
DailyScrum. We don't want to lose that data, and so we must migrate those objects to the new schema when the app is upgraded.
Fortunately, Realm has built-in functionality to automatically handle the addition and deletion of fields. When adding a field, Realm will use a default value (e.g.,
If we simply upgrade the installed app with the one using the new schema, then we'll get a fatal error. That's because we need to tell Realm that we've updated the schema. We do that by setting the schema version to 1 (the version defaulted to 0 for the original schema):
The second feature request is to show the number of attendees in the history from each meeting:
We increment the schema version to 2. Note that the schema version applies to all Realm objects, and so we have to set the version to 2 even though this is the first time that we've changed the schema for
If we leave it to Realm to initialize
numberOfAttendees, then it will set it to 0—which is not what we want. Instead, we provide a
migrationBlockwhich initializes new fields based on the old schema version:
Note that all other fields are migrated automatically.
It's up to you how you use data from the previous schema to populate fields in the new schema. E.g., if you wanted to combine
lastNamefrom the previous schema to populate a
fullNamefield in the new schema, then you could do so like this:
We can't know what "old version" of the schema will be already installed on a user's device when it's upgraded to the latest version (some users may skip some versions,) and so the
migrationBlockmust handle all previous versions. Best practice is to process the incremental schema changes sequentially:
oldSchemaVersion < 1: Process the delta between v0 and v1
oldSchemaVersion < 2: Process the delta between v1 and v2
oldSchemaVersion < 3: Process the delta between v2 and v3
Realm Studio shows that our code has correctly initialized
It's almost inevitable that any successful mobile app will need some schema changes after it's gone into production. Realm makes adapting to those changes simple, ensuring that users don't lose any of their existing data when upgrading to new versions of the app.
For changes such as adding or removing fields, all you need to do as a developer is to increment the version with each new deployed schema. For more complex changes, you provide code that computes the values for fields in the new schema using data from the old schema.
If you're working with an app for a different platform, then you can find instructions in the docs: