Change an Object Model - Swift SDK
On this page
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.
Overview
When you update your object schema, you must increment the schema version and perform a migration.
Tip
See also:
This page provides general Swift and Objective-C migration examples. If you are using Realm with SwiftUI, see the SwiftUI-specific migration examples.
If your schema update adds optional properties or removes properties,
Realm 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
Tip
Bypass Migration During Development
When developing or debugging your application, you may prefer to delete the realm instead of migrating it. Use the deleteRealmIfMigrationNeeded flag to delete the database automatically when a schema mismatch would require a migration.
Never release an app to production with this flag set to true.
Schema Version
A schema version identifies the state of a Realm Schema at some point in time. Realm tracks the schema version of each realm and uses it to map the objects in each realm to the correct schema.
Schema versions are integers that you may include
in the realm configuration when you open a realm. If a client
application does not specify a version number when it opens a realm then
the realm defaults to version 0.
Important
Increment Versions Monotonically
Migrations must update a realm to a higher schema version. Realm will throw an error if a client application opens a realm with a schema version that is lower than the realm's current version or if the specified schema version is the same as the realm's current version but includes different object schemas.
Migrations
A local migration is a migration for a realm that does not automatically Sync with another realm. Local migrations have access to the existing Realm Schema, version, and objects and define logic that incrementally updates the realm to its new schema version. To perform a local migration you must specify a new schema version that is higher than the current version and provide a migration function when you open the out-of-date realm.
In iOS, you can update underlying data to reflect schema changes using manual migrations. During such a manual migration, you can define new and deleted properties when they are added or removed from your schema.
Automatically Update Schema
Add a Property
Realm can automatically migrate added properties, but you must specify an updated schema version when you make these changes.
Note
Realm 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 automatically migrates the realm to conform to
the updated Person schema. But the developer must set the realm's
schema version to 2.
Delete a Property
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 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.
Manually Migrate Schema
For more complex schema updates, Realm requires a manual migration for old instances of a given object to the new schema.
Rename a Property
To rename a property during a migration, use the Migration.renameProperty(onType:from:to:) method.
Realm applies any new nullability or indexing settings during the rename operation.
Example
Rename age to yearsSinceBirth within a migrationBlock.
Modify Properties
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.
Convert from Object to EmbeddedObject
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.
Tip
See also:
Additional Migration Examples
Please check out the additional migration examples on the realm-swift repo.