How to perform a lightweight migration in Core Data

A database migration is performed whenever we need to make changes to the data model.

For a specific set of changes, Core Data can perform an almost automatic data migration, also called lightweight migration. Examples of those changes are adding, renaming or deleting entities, attributes or relationships or changing the relationship type.

When changes to the data model exceed the capabilities of a lightweight migration, we need to do a heavyweight i.e. manual migration.

In this guide, we are going to look at how to perform a lightweight migration in Core Data.

Preparing for a technical iOS job interview

Check out my new book on preparing for a technical iOS job interview with over 200 questions & answers. Test your knowledge on iOS topics such as Swift & Objective-C, SwiftUI & UIKit, Combine, HTTP Networking, Authentication, Core Data, Concurrency with async/await, Security, Automated Testing and more.

LEARN MORE

Steps to perform a lightweight migration in Core Data

To perform a lightweight migration in Core Data, basically the following steps are required:

1. Enabling the lightweight migration option when setting up the Core Data stack.
2. Creating a new data model version.
3. Modifying the new data model version. For some changes, setting renaming identifiers.

Let's look at these steps in more detail.

1. Enabling the lightweight migration option when setting up the Core Data stack

When we use the NSPersistentContainer class to create and manage the Core Data stack, we don't need to do any additional setup work, the lightweight migration is automatically activated for us.

When building our own Core data stack, we can activate lightweight migration by passing in an options dictionary when adding a persistent store.

let coordinator = NSPersistentStoreCoordinator(managedObjectModel: managedObjectModel)
let options = [NSMigratePersistentStoresAutomaticallyOption: true,
                        NSInferMappingModelAutomaticallyOption: true]
do {
    try coordinator.addPersistentStore(ofType: NSSQLiteStoreType, configurationName: nil, at: url, options: options)
} catch {
    // handle error
}

2. Creating a new data model version

To perform automatic lightweight migration, Core Data generates an inferred mapping model. To do that, Core Data needs the new and the old data model.

For that reason, changing a data model that already has been shipped to users would result in a data base error. To avoid that, we can create a new model version by selecting Editor > Add Model Version in Xcode's menu. This will add a new .xcdatamodel file to our project:

After adding a new version, we can set it to the current version in Xcode's File Inspector.

3. Modifying the new data model version

Now, we can start making changes to the new data model. For Core Data to be able to create an inferred mapping model, the changes must fit a specific pattern, for example:

• Adding or deleting entities, attributes or relationships.
• Renaming entities, attributes or relationships by setting the renaming identifier to the name of the corresponding property or entity in the previous model in Xcode's Data Model inspector.
• Changing required attributes to optional attributes or vice versa with a default value.
• Changing a relationship from to-one to to-many, or a nonordered to an ordered relationship.

To check in advance whether Core Data can infer the mapping model, we can use the inferredMappingModel(forSourceModel:destinationModel:) method of NSMappingModel:

let inferredModel = try? NSMappingModel.inferredMappingModel(forSourceModel: managedObjectModel, destinationModel: managedObjectModel)
if (inferredModel != nil) {
    // Lightweight migration is possible
}

If our changes exceed the capabilities of an automatic migration, we would need to perform a heavyweight e.g. manual migration. But this is a topic for another day.

Preparing for a technical iOS job interview

Check out my new book on preparing for a technical iOS job interview with over 200 questions & answers. Test your knowledge on iOS topics such as Swift & Objective-C, SwiftUI & UIKit, Combine, HTTP Networking, Authentication, Core Data, Concurrency with async/await, Security, Automated Testing and more.

LEARN MORE