Lightweight Coredata Migration

Since we’ve faced migration issues quite often, I am writing this up to help everyone understand how the Lightweight Coredata Migration works.


To understand how the Coredata Lightweight Migration can be used in our project to support data model changes.

When do we need to migrate the data?

As and when we modify, add or remove any Entity from Coredata, the data stored in earlier versions of the app needs to be migrated to the new & updated data model. Changing the keyname, data type of a key, adding a new key, removing a key from an entity, these are some examples of modifying the existing Entity.

We can do this multiple ways, the easiest and ideal way is to use Light Weight Migration.

What is Lightweight Coredata Migration?

Ligheweight Coredata migration is the easiest and simplest way of migrating data models with least possible efforts. Using this method, coredata migrates the data automatically. There are some limitations on how much you can change the data model, since this method requires the least amount of work, it’s preferred migration method.

How to use Lightweight Coredata Migration?

Let’s say we have an existing data model named Person in our app:

lightweight coredata migration
Person Coredata Model – without Age

We release the app with this data model and now the user’s data is stored in the coredata.

Now we have a new feature of recording Age. So we need to add a key to store this data. The updated model would look something like this:

lightweight coredata migration
Person Coredata Model – with Age

Before making these changes to the coredata model the data stored in the user’s device does not have this key, so we need to migrate the coredata.

The First Step: Create New Data Model

  • Go to our xcode project
  • Open the file navigator panel on the left. 
  • Select the Coreadata model and go to Editor menu- Select Add Model Version
  • In the prompt, you can give any name you want. However the convention we will follow is to increase the version number. e.g CoreData_v2 => CoreData_v3.
  • Select the current model as the Base model. This step will create a second version of the data model, but you still need to tell Xcode to use the new version as the current model.

The Second Step: Use the New Data Model

In order to perform any migration, you want to keep the original model file as it is, and make changes to the new model file.

In the File Inspector pane on the right, there is a selection menu toward the bottom called Model Version. Change that selection to match the name of the new data model, CoreData_v3.

lightweight coredata migration
File Inspector Pan – Model Version

Once you’ve made that change, notice that the little green check mark icon in the project navigator has moved from the previous data model to the new data model.

lightweight coredata migration
Project Navigator – Coredata Model File

Core Data will try to first connect the persistent store with the ticked model version when setting up the stack. If a store file was found, and it isn’t compatible with this model file, a migration will be triggered. The older version is there to support the migration.

The Last Step: Modify the New Data Model

Now that we have the new data model setup, we can go ahead and make the changes to the new model.

In our example, we wanted to add Age key. Add it and the updated model will be:

lightweight coredata migration
Person Coredata Model – with Age

Now build and run the project to compile these changes. There you go! You can now use this key wherever you want and handle the database operations.


The Lightweight Coredata migration is very easy to use and a handy tool. We MUST follow the above mentioned process to avoid any future crashes related to Coredata.

Read more on this at Apple Documentation.

If you want to learn how to use SwiftUI in your existing app, then you can read it here!

or If you want to learn how to use and convert your UIViewControllers in SwiftUI, then you can read it here!

Like it? Share with your friends!


Your email address will not be published. Required fields are marked *