Core Data Model Versioning and Data Migration

Core Data provides support for managing changes to a managed object model as your application evolves.

You can only open a Core Data store using the managed object model used to create it. Changing a model will therefore make it incompatible with (and so unable to open) the stores it previously created. If you change your model, you therefore need to change the data in existing stores to new version—changing the store format is known as migration.

To migrate a store, you need both the version of the model used to create it, and the current version of the model you want to migrate to. You can create a versioned model that contains more than one version of a managed object model. Within the versioned model you mark one version as being the current version. Core Data can then use this model to open persistent stores created using any of the model versions, and migrate the stores to the current version. To help Core Data perform the migration, though, you may have to provide information about how to map from one version of the model to another. This information may be in the form of hints within the versioned model itself, or in a separate mapping model file that you create.

At a Glance

Typically, as it evolves from one version to another, numerous aspects of your application change: the classes you implement, the user interface, the file format, and so on. You need to be aware of and in control of all these aspects; there is no API that solves the problems associated with all these—for example Cocoa does not provide a means to automatically update your user interface if you add a new attribute to an entity in your managed object model. Core Data does not solve all the issues of how you roll out your application. It does, though, provide support for a small—but important and non-trivial—subset of the tasks you must perform as your application evolves.

• Model versioning allows you to specify and distinguish between different configurations of your schema.

  There are two distinct views of versioning: your perspective as a developer, and Core Data’s perspective. These may not always be the same. The differences are discussed in Understanding Versions.

  The format of a versioned managed object model, and how you add a version to a model, is discussed in Model File Format and Versions.

• Core Data needs to know how to map from the entities and properties in a source model to the entities and properties in the destination model.

  In many cases, Core Data can infer the mapping from existing versions of the managed object model. This is described in Lightweight Migration.

  If you make changes to your models such that Core Data cannot infer the mapping from source to destination, you need to create a mapping model. A mapping model parallels a managed object model, specifying how to transform objects in the source into instances appropriate for the destination.

  How you create a mapping model is discussed in Mapping Overview.

• Data migration allows you to convert data from one model (schema) to another, using mappings.

  The migration process itself is discussed in The Migration Process.

  How you perform a migration is discussed in Initiating the Migration Process.

  You can also customize the migration process—that is, how you programmatically determine whether migration is necessary; how you find the correct source and destination models and the appropriate mapping model to initialize the migration manager; and then how you perform the migration.

  You only customize the migration process if you want to initiate migration yourself. You might do this to, for example, search locations other than the application’s main bundle for models or to deal with large data sets by performing the migration in several passes using different mapping models.

  How you can customize the process is described in Customizing the Migration Process.

• If you are using iCloud, there are some constraints on what migration you can perform.

  If you are using iCloud, you must use lightweight migration. Other factors to be aware of are described in Migration and iCloud.

Although Core Data makes versioning and migration easier than would typically otherwise be the case, these processes are still non-trivial in effect. You still need to carefully consider the implications of releasing and supporting different versions of your application.

Prerequisites

This document assumes that you are familiar with the Core Data architecture and the fundamentals of using Core Data. You should be able to identify the parts of the Core Data stack and understand the roles of the model, the managed object context, and the persistent store coordinator. You need to know how to create a managed object model, how to create and programmatically interact with parts of the Core Data stack.

If you do not meet these requirements, you should first read the Core Data Programming Guide and related materials. You are strongly encouraged also to work through the Core Data Utility Tutorial.