Initiating the Migration Process

When you initialize a persistent store coordinator, you assign to it a managed object model (see initWithManagedObjectModel:); the coordinator uses that model to open persistent stores. You open a persistent store using addPersistentStoreWithType:configuration:URL:options:error:. How you use this method, however, depends on whether your application uses model versioning and on how you choose to support migration—whether you choose to use the default migration process or custom version skew detection and migration bootstrapping. The following list describes different scenarios and what you should do in each:

• Your application does not support versioning

  You use addPersistentStoreWithType:configuration:URL:options:error: directly.

  If for some reason the coordinator’s model is not compatible with the store schema (that is, the version hashes current model’s entities do not equal those in the store’s metadata), the coordinator detects this, generates an error, and addPersistentStoreWithType:configuration:URL:options:error: returns NO. You must deal with this error appropriately.

• Your application does support versioning and you choose to use either the lightweight or the default migration process

  You use addPersistentStoreWithType:configuration:URL:options:error: as described in Lightweight Migration and The Default Migration Process respectively.

  The fundamental difference from the non-versioned approach is that you instruct the coordinator to automatically migrate the store to the current model version by adding an entry to the options dictionary where the key is NSMigratePersistentStoresAutomaticallyOption and the value is an NSNumber object that represents YES.

• Your application does support versioning and you choose to use custom version skew detection and migration bootstrapping

  Before opening a store you use isConfiguration:compatibleWithStoreMetadata: to check whether its schema is compatible with the coordinator’s model:

  • If it is, you use addPersistentStoreWithType:configuration:URL:options:error: to open the store directly;

  • If it is not, you must migrate the store first then open it (again using addPersistentStoreWithType:configuration:URL:options:error:).

  You could simply use addPersistentStoreWithType:configuration:URL:options:error: to check whether migration is required, however this is a heavyweight operation and inefficient for this purpose.

It is important to realize that there are two orthogonal concepts:

1. You can execute custom code during the migration.

2. You can have custom code for version skew detection and migration bootstrapping.

The migration policy classes allow you to customize the migration of entities and properties in a number of ways, and these are typically all you need. You might, however, use custom skew detection and migration bootstrapping so that you can take control of the migration process. For example, if you have very large stores you could set up a migration manager with the two data models, and then use a series of mapping models to migrate your data into your destination store (if you use the same destination URL for each invocation, Core Data adds new objects to the existing store). This allows the framework (and you) to limit the amount of data in memory during the conversion process.

The Default Migration Process

To open a store and perform migration (if necessary), you use addPersistentStoreWithType:configuration:URL:options:error: and add to the options dictionary an entry where the key is NSMigratePersistentStoresAutomaticallyOption and the value is an NSNumber object that represents YES. Your code looks similar to the following example:

Listing 6-1  Opening a store using automatic migration

NSError *error;

NSPersistentStoreCoordinator *psc = <#The coordinator#>;

NSURL *storeURL = <#The URL of a persistent store#>;

NSDictionary *optionsDictionary =

    [NSDictionary dictionaryWithObject:[NSNumber numberWithBool:YES]

                    forKey:NSMigratePersistentStoresAutomaticallyOption];

NSPersistentStore *store = [psc addPersistentStoreWithType:<#Store type#>

                                configuration:<#Configuration or nil#>

                                URL:storeURL

                                options:optionsDictionary

                                error:&error];

If the migration proceeds successfully, the existing store at storeURL is renamed with a “~” suffix before any file extension and the migrated store saved to storeURL.

In its implementation of addPersistentStoreWithType:configuration:URL:options:error: Core Data does the following:

1. Tries to find a managed object model that it can use to open the store.

   Core Data searches through your application’s resources for models and tests each in turn. If it cannot find a suitable model, Core Data returns nil and a suitable error.

2. Tries to find a mapping model that maps from the managed object model for the existing store to that in use by the persistent store coordinator.

   Core Data searches through your application’s resources for available mapping models and tests each in turn. If it cannot find a suitable mapping, Core Data returns NO and a suitable error.

   Note that you must have created a suitable mapping model in order for this phase to succeed.

3. Creates instances of the migration policy objects required by the mapping model.

Note that even if you use the default migration process you can customize the migration itself using custom migration policy classes.