Understanding migrations in Realm - Swift

Question

I'm trying to understand migrations, can someone describe situations where migrations are required?

For instance let's pretend for a moment that an app has been released and the following Realm objects were used but now version 2 needs to be released and a new Realm object was added to this new version, do I need a migration?

Version 1

import Foundation
import RealmSwift

class Item:Object{
    dynamic var productName:String = ""
    dynamic var createdAt = NSDate()
}


import Foundation
import RealmSwift

class ItemList: Object {
    dynamic var listName = ""
    dynamic var createdAt = NSDate()
    let items = List<Item>()
}

Version 2

Version 2 needs a new object.

import Foundation
import RealmSwift

class Item:Object{
    dynamic var productName:String = ""
    dynamic var createdAt = NSDate()
}


import Foundation
import RealmSwift

class ItemList: Object {
    dynamic var listName = ""
    dynamic var createdAt = NSDate()
    let items = List<Item>()
}

// New object for version 2
import Foundation
import RealmSwift

class NewObjec:Object{
    dynamic var someString:String = ""
    dynamic var createdAt = NSDate()
}

Do I need to create a migration if existing objects didn't change but an extra object was added?

In general, can someone describe the situations where migrations are needed?

Thanks a lot

Answer 1

No, you should update the schema version because the Realm schema has been updated, but you don't have to add a migration block. You could consider Realm as a real database, so in this case it's like your adding a new "column".

In this realm doc section you can find the following block:

// Set the block which will be called automatically when opening a Realm with
// a schema version lower than the one set above
migrationBlock: { migration, oldSchemaVersion in
  // We haven’t migrated anything yet, so oldSchemaVersion == 0
  if (oldSchemaVersion < 1) {
    // Nothing to do!
    // Realm will automatically detect new properties and removed properties
    // And will update the schema on disk automatically
  }
})

You can omit the migration block, updating the Realm version if you're just adding/removing properties:

Realm.Configuration(schemaVersion: 2)

As you can see, they say you have to update schema version, then it will automatically update the realm schema adding new (or removed) properties.

In case you're gonna make "special" changes, you have to fill the migration block with you're logic. Take a look at this:

Version 1:

class Person: Object {
    dynamic var firstName = ""
    dynamic var lastName = ""
    dynamic var age = 0
}

Version 2:

class Person: Object {
    dynamic var fullName = ""
    dynamic var age = 0
}

In this case, you're not just adding fullName and removing firstName, lastName, but you're combining them, so it is necessary a custom logic.

migrationBlock: { migration, oldSchemaVersion in
  if (oldSchemaVersion < 1) {
    // 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)"
    }
  }
})

In conclusion, you need to update schema version every time you update your Models, but you don't need to write a migration block if you're just adding/removing properties.

Edit: Thanks to Dávid Pásztor for suggestions