Modify an Object Schema - iOS SDK

When the schema of an object changes, Realm Database requires a migration for any old instances of a given object to the new schema. Realm Database can automatically migrate added and removed properties, but does not automatically set values for new properties unless the new object schema specifies a default value.

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.


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

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

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.

// In the second version, the Person model has one
// combined field for the name. A migration will be required
// to convert from version 1 to version 2.
class Person: Object {
@objc dynamic var fullName = ""
@objc dynamic var age = 0
// In application(_:didFinishLaunchingWithOptions:)
let config = Realm.Configuration(
schemaVersion: 2, // Set the new schema version.
migrationBlock: { migration, oldSchemaVersion in
if oldSchemaVersion < 2 {
// The enumerateObjects(ofType:_:) method iterates over
// every Person object stored in the Realm file
migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
// combine name fields into a single field
let firstName = oldObject!["firstName"] as? String
let lastName = oldObject!["lastName"] as? String
newObject!["fullName"] = "\(firstName!) \(lastName!)"
// Tell Realm to use this new configuration object for the default Realm
Realm.Configuration.defaultConfiguration = config
// Now that we've told Realm how to handle the schema change, opening the file
// will automatically perform the migration
let realm = try! Realm()
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.

let config = Realm.Configuration(
schemaVersion: 1,
migrationBlock: { migration, oldSchemaVersion in
// We haven’t migrated anything yet, so oldSchemaVersion == 0
if oldSchemaVersion < 1 {
// The renaming operation should be done outside of calls to `enumerateObjects(ofType: _:)`.
migration.renameProperty(onType: Person.className(), from: "yearsSinceBirth", to: "age")

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

Give Feedback