Logo for tanaschita.com

How to perform a lightweight migration in Core Data

Learn the possibilities Core Data provides to migrate model changes.

19 Dec 2022 · 4 min read

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.

Sponsorship logo
Preparing for a technical iOS job interview - updated for iOS 17
Check out my book on preparing for a technical iOS job interview with over 200 questions & answers. Test your knowledge on iOS topics such as Swift, SwiftUI, Combine, HTTP Networking, Authentication, SwiftData & Core Data, Concurrency with async/await, Security, Automated Testing, Machine Learning 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:

Adding a new data model version
Adding a new data model version.

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.

Sponsorship logo
Preparing for a technical iOS job interview - updated for iOS 17
Check out my book on preparing for a technical iOS job interview with over 200 questions & answers. Test your knowledge on iOS topics such as Swift, SwiftUI, Combine, HTTP Networking, Authentication, SwiftData & Core Data, Concurrency with async/await, Security, Automated Testing, Machine Learning and more.
LEARN MORE

Newsletter

Image of a reading marmot
Subscribe

Like to support my work?

Say hi

Related tags

Articles with related topics

core data

persistence

xcode

ios

How to handle non-optional Core Data properties in Swift

Explore the possibilities to use non-optional Swift values in Core Data.

07 Nov 2022 · 4 min read

Latest articles and tips

© 2024 tanaschita.com

Privacy policy

Impressum