Tuesday, August 16, 2016

Migrating a Core Data Model in One Minute

Database migrations can be a scary subject to beginners, especially if user data is on the line. While developing an app, you're probably used to resetting the simulator and reinstalling whenever you need to change the data model. Unfortunately, this quick-and-dirty solution won't cut it for a production app. You'll inevitably need to migrate the data the "right" way in order to keep your users happy. Fortunately, Apple once again succeeds in simplifying even the most daunting tasks, and its built right in to the Core Data framework. The best part is that it only takes about a minute.

To start, you can create a new project with the master-detail template with "Use Core Data" checked. Or you can download a pre-made template here. The examples in this tutorial use Swift.

To begin, open up your .xcdatamodeld file and select "Editor > Add Model Version" from the menu. There should be two fields (one with "Version Name" filled in and a dropdown titles "Based on Model". This second field should point to the latest model version. The name "Master_Detail 2" will work, so just click "Finish".

The .xcdatamodeld file should now look like a folder, and the new model should be inside.

For demonstrational purposes, we'll just add a new property to version 2 of the model.

That's all for the changes. All we have to do now is tell our app which model version to use. With the .xcdatamodeld file still selected in the left pane, head over to the file inspector and make sure Current is set to "Master_Detail_2" under the Model Version section.

Finally, since this is the first migration, we need to modify some code in order for everything to work. In the lazy variable "persistentStoreCoordinator" found in the AppDelegate, modify the end of the getter to look like this.

The dictionary specifies the necessary properties to automatically migrate the database. We then pass this as the "options" parameter when we call addPersistentStoreWithType(). For the full list of available options, you can refer to the documentation for NSPersistentStoreCoordinator.

And we're done. To recap, here's what we did.
  1. Created a new model version from the model editor. 
  2. Edited the schema by adding a new attribute. 
  3. Set the new model as the current version. 
  4. Configured our persistent store coordinator to automatically migrate the database. 
Ok, maybe that took two minutes (feel free to post your time in the comments), but it's definitely a straightforward process to do. There are situations where this lightweight migration method won't be enough, but it's a simple way to make minor changes to the data model. No more reinstalling and losing data: just happy users.


  1. I recently came across your blog and have been reading along. Nice blog. I will keep visiting this blog very often. Hire Android App Developer

  2. As an example, let's say you run a small business with 5 employees. You have a few hundred customers. Their orders, your order fulfillment, and your administrative procedures are straightforward. A database in Microsoft Access can handle that with no problem.
    dashboard software