Docs Menu

Modify an Object Schema - iOS SDK

On this page

  • Overview
  • Automatically Update Schema
  • Add a Property
  • Delete a Property
  • Manually Migrate Schema
  • Rename a Property
  • Modify Properties
  • 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 optional properties or removes properties, Realm Database can perform the migration automatically. You only need to increment the schemaVersion.

For more complex schema updates, you must also manually specify the migration logic in a migrationBlock. This might include changes such as:

  • Adding required properties that must be populated with default values
  • Combining fields
  • Renaming a field
  • Changing a field's type
  • Converting from an object to an embedded object

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

Note

Realm Database does not automatically set values for new required properties. You must use a migration block to set default values for new required properties. For new optional properties, existing records can have null values. This means you don't need a migration block when adding optional properties.

Example

A realm using schema version 1 has a Person object type that has first name, last name, and age properties:

The developer decides that the Person class needs an email field and updates the schema.

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.

To delete a property from a schema, remove the property from the object's class and set a schemaVersion of the realm's configuration object. Deleting a property will not impact existing objects.

Example

A realm using schema version 1 has a Person object type that has first name, last name, and age properties:

The developer decides that the Person does not need the age field and updates the schema.

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.

Tip

SwiftUI developers may see an error that a migration is required when they add or delete 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.

For more complex schema updates, Realm Database requires a manual migration for old instances of a given object to the new schema.

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.

Example

Rename age to yearsSinceBirth within a migrationBlock.

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 and updates the schema.

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.

Later, the developer decides that the age field should be of type String rather than Int and updates the schema.

To migrate the realm to conform to the updated Person schema, the developer sets the realm's schema version to 3 and adds a conditional to the migration function so that the function defines how to migrate from any previous version to the new one.

Tip
Linear Migrations

Avoid nesting or otherwise skipping if (oldSchemaVersion < X) statements in migration blocks. This ensures that all updates can be applied in the correct order, no matter which schema version a client starts from. The goal is to define migration logic which can transform data from any outdated schema version to match the current schema.

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
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.