Core Data Must Be Able to Infer the Mapping

To perform automatic lightweight migration, Core Data needs to be able to find the source and destination managed object models itself at runtime. Core Data looks for models in the bundles returned by NSBundle’s allBundles and allFrameworks methods. If you store your models elsewhere, you must follow the steps described in Use a Migration Manager if Models Cannot Be Found Automatically . Core Data must then analyze the schema changes to persistent entities and properties and generate an inferred mapping model.

For Core Data to be able to generate an inferred mapping model, changes must fit an obvious migration pattern, for example:

• Simple addition of a new attribute

• Removal of an attribute

• A non-optional attribute becoming optional

• An optional attribute becoming non-optional, and defining a default value

• Renaming an entity or property

If you rename an entity or property, you can set the renaming identifier in the destination model to the name of the corresponding property or entity in the source model. You set the renaming identifier in the managed object model using the Xcode Data Modeling tool’s property inspector (for either an entity or a property). For example, you can:

• Rename a Car entity to Automobile

• Rename a Car’s color attribute to paintColor

The renaming identifier creates a “canonical name,” so you should set the renaming identifier to the name of the property in the source model (unless that property already has a renaming identifier). This means you can rename a property in version 2 of a model then rename it again version 3, and the renaming will work correctly going from version 2 to version 3 or from version 1 to version 3.

In addition, Core Data supports:

• Adding relationships and changing the type of relationship

  • You can add a new relationship or delete an existing relationship.

  • Renaming a relationship (by using a renaming identifier, just like an attribute)

  • Changing a relationship from a to-one to a to-many, or a non-ordered to-many to ordered (and visa-versa)

• Changing the entity hierarchy

  • You can add, remove, rename entities

  • You can create a new parent or child entity and move properties up and down the entity hierarchy

  • You can move entities out of a hierarchy

    You cannot, however, merge entity hierarchies; if two existing entities do not share a common parent in the source, they cannot share a common parent in the destination

Request Automatic Migration Using an Options Dictionary

You request automatic lightweight migration using the options dictionary you pass in addPersistentStoreWithType:configuration:URL:options:error:, by setting values corresponding to both the NSMigratePersistentStoresAutomaticallyOption and the NSInferMappingModelAutomaticallyOption keys to YES:

NSError *error = nil;

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

NSPersistentStoreCoordinator *psc = <#The coordinator#>;

NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys:

    [NSNumber numberWithBool:YES], NSMigratePersistentStoresAutomaticallyOption,

    [NSNumber numberWithBool:YES], NSInferMappingModelAutomaticallyOption, nil];

BOOL success = [psc addPersistentStoreWithType:<#Store type#>

                    configuration:<#Configuration or nil#> URL:storeURL

                    options:options error:&error];

if (!success) {

    // Handle the error.

}

If you want to determine in advance whether Core Data can infer the mapping between the source and destination models without actually doing the work of migration, you can use NSMappingModel’s inferredMappingModelForSourceModel:destinationModel:error: method. This returns the inferred model if Core Data is able to create it, otherwise nil.

Use a Migration Manager if Models Cannot Be Found Automatically

To perform automatic migration, Core Data has to be able to find the source and destination managed object models itself at runtime (see Core Data Must Be Able to Infer the Mapping). If you need to put your models in the locations not checked by automatic discovery, then you need to generate the inferred model and initiate the migration yourself using a migration manager (an instance of NSMigrationManager).

The following code sample illustrates how to generate an inferred model and initiate the migration using a migration manager. The code assumes that you have implemented two methods—sourceModel and destinationModel—that return the source and destination managed object models respectively.

- (BOOL)migrateStore:(NSURL *)storeURL toVersionTwoStore:(NSURL *)dstStoreURL error:(NSError **)outError {

    // Try to get an inferred mapping model.

    NSMappingModel *mappingModel =

        [NSMappingModel inferredMappingModelForSourceModel:[self sourceModel]

                        destinationModel:[self destinationModel] error:outError];

    // If Core Data cannot create an inferred mapping model, return NO.

    if (!mappingModel) {

        return NO;

    }

    // Create a migration manager to perform the migration.

    NSMigrationManager *manager = [[NSMigrationManager alloc]

        initWithSourceModel:[self sourceModel] destinationModel:[self destinationModel]];

    BOOL success = [manager migrateStoreFromURL:storeURL type:NSSQLiteStoreType

        options:nil withMappingModel:mappingModel toDestinationURL:dstStoreURL

        destinationType:NSSQLiteStoreType destinationOptions:nil error:outError];

    return success;

}