Modify an Object Schema - Android SDK¶
The following examples demonstrate how to add, delete, and modify properties in a schema. First, make the required schema change. Then, create a corresponding migration function to move data from the original schema to the updated schema.
Assume that each schema change in this example occurs after an application has used each version for some amount of time. New schema version numbers only apply once you open the realm with an updated schema and explicitly specify the new version number, so in order to get to version 3, you would first need to open the app with versions 1 and 2.
A realm using schema version 0
has a Person
object type:
class Person: RealmObject { // Realm schema version 0 var firstName: String = "" var age: int = 0 }
Add a Property¶
The following example adds a lastName
property to the
original Person schema:
class Person: RealmObject { // Realm schema version 1 var firstName: String = "" var lastName: String = "" var age: int = 0 }
Delete a Property¶
The following example uses a combined
fullName
property instead of the separate firstName
and
lastName
property in the original Person schema:
class Person: RealmObject { // Realm schema version 2 var fullName: String = "" var age: int = 0 }
Modify a Property Type or Rename a Property¶
The following example modifies the age
property in the
original Person schema by
renaming it to birthday
and changing the type to Date
:
class Person: RealmObject { // Realm schema version 3 var fullName: String = "" var birthday: Date = new Date(); }
Migration Functions¶
To migrate the realm to conform to the updated
Person
schema, set the realm's
schema version to 3
and define a migration function to set the value of
fullName
based on the existing firstName
and
lastName
properties and the value of birthday
based on
age
:
val migration = object: RealmMigration { override fun migrate(realm: DynamicRealm, oldVersion: Long, newVersion: Long) { var version: Long = oldVersion // DynamicRealm exposes an editable schema val schema: RealmSchema = realm.schema // Changes from version 0 to 1: Adding lastName. // All properties will be initialized with the default value "". if (version == 0L) { schema.get("Person")!! .addField("lastName", String::class.java, FieldAttribute.REQUIRED) version++ } // Changes from version 1 to 2: Combining firstName/lastName into fullName if (version == 1L) { schema.get("Person")!! .addField("fullName", String::class.java, FieldAttribute.REQUIRED) .transform { obj: DynamicRealmObject -> val name = "${obj.getString("firstName")} ${obj.getString("lastName")}" obj.setString("fullName", name) } .removeField("firstName") .removeField("lastName") version++ } // Changes from version 2 to 3: Replace age with birthday if (version == 2L) { schema.get("Person")!! .addField("birthday", Date::class.java, FieldAttribute.REQUIRED) .transform { obj: DynamicRealmObject -> var birthYear = Date().year - obj.getInt("age") obj.setDate("birthday", Date(birthYear, 1, 1)) } .removeField("age") version++ } } } class Module val config = RealmConfiguration.Builder() .schemaVersion(3) // Must be bumped when the schema changes .migration(migration) // Migration to run instead of throwing an exception .build()
You can use the RealmConfiguration.shouldDeleteRealmIfMigrationNeeded() builder method when constructing a realm to delete the realm instead of performing a migration when a migration is required. This can come in handy during development when schemas often change.