Navigation

Modify an Object Schema - iOS SDK

On this page

  • Overview
  • Update a Schema Version
  • Perform a Schema Migration
  • Rename a Property
  • Convert from Object to EmbeddedObject
  • Additional Migration Examples
Note
Modify Schema Properties of a Synced Realm

The following page demonstrates how to modify schema properties of a local realm. Learn how to modify schema properties of a synced realm.

When you update your object schema, you must increment the schema version and perform a migration.

If your schema update adds or removes properties, Realm Database can perform the migration automatically, and you only need to increment the schemaVersion.

For more complex schema updates, such as combining fields, renaming fields, or converting from an object to an embedded object, you must also specify the migration logic in a migrationBlock.

Realm Database can automatically migrate added and removed properties, but you must specify an updated schema version when you make these changes.

Note

Realm Database does not automatically set values for new properties unless the new object schema specifies a default value.

Example

A realm using schema version 1 has a Person object type that has separate fields for first and last names, and an age field:

// In the first version of the app, the Person model
// has separate fields for first and last names,
// and an age property.
class Person: Object {
@Persisted var firstName = ""
@Persisted var lastName = ""
@Persisted var age = 0
}

The developer decides that the Person class does not need an age field, but does need an email field.

// In a new version, you add or remove properties
// on the Person model.
class Person: Object {
@Persisted var firstName = ""
@Persisted var lastName = ""
// New and removed properties can be migrated
// automatically, but must update the schema version.
// Add a new "email" property, and remove the
// "age" property.
@Persisted var email = ""
// @Persisted var age = 0
}

Realm Database automatically migrates the realm to conform to the updated Person schema. But the developer must set the realm's schema version to 2.

// When you open the file, specify that the schema
// is now using a newer version.
let config = Realm.Configuration(
schemaVersion: 2)
Tip

SwiftUI developers may see an error that a migration is required when they add or remove properties. This is related to the lifecycle in SwiftUI. The Views are laid out, and then the .environment modifier sets the config.

To resolve a migration error in these circumstances, pass Realm.Configuration(schemaVersion: <Your Incremented Version>) into the ObservedResults constructor.

When the schema of an object changes, Realm Database requires a migration for old instances of a given object to the new schema.

Tip

You can use the deleteRealmIfMigrationNeeded method to delete the realm if it would require a migration. This can be useful during development when you need to iterate quickly and don't want to perform the migration.

To define custom migration logic, set the migrationBlock property of the Configuration when opening a realm.

The migration block receives a Migration object that you can use to perform the migration. You can use the Migration object's enumerateObjects(ofType:_:) method to iterate over and update all instances of a given Realm type in the realm.

Example

A realm using schema version 1 has a Person object type that has separate fields for first and last names:

The developer decides that the Person class should use a combined fullName field instead of the separate firstName and lastName fields.

To migrate the realm to conform to the updated Person schema, the developer sets the realm's schema version to 2 and defines a migration function to set the value of fullName based on the existing firstName and lastName properties.

Tip
Linear Migrations

Avoid nesting if (oldSchemaVersion < X) statements in migration blocks. This ensures that users see all upgrades, no matter which schema version they start from.

To rename a property during a migration, use the Migration.renameProperty(onType:from:to:) method.

Realm Database applies any new nullability or indexing settings during the rename operation.

Embedded objects cannot exist independently of a parent object. When changing an Object to an EmbeddedObject, the migration block must ensure that every embedded object has exactly one backlink to a parent object. Having no backlinks or multiple backlinks raises the following exceptions:

At least one object does not have a backlink (data would get lost).
At least one object does have multiple backlinks.

Please check out the additional migration examples on the realm-cocoa repo.

Give Feedback

On this page

  • Overview
  • Update a Schema Version
  • Perform a Schema Migration
  • Rename a Property
  • Convert from Object to EmbeddedObject
  • Additional Migration Examples