Using Lightweight Migration

Request lightweight (automatic) migration to update your data model to match changes in your app.


Core Data can typically perform an automatic data migration, referred to as lightweight migration. Lightweight migration infers the migration from the differences between the source and the destination managed object models.

Generating an Inferred Mapping Model

To perform automatic lightweight migration, Core Data needs to be able to find the source and destination managed object models at runtime. It looks for models in the bundles returned by the allBundles and allFrameworks methods of the NSBundle class. Core Data then analyzes the schema changes to persistent entities and properties, and generates an inferred mapping model.

Generating an inferred mapping model requires changes to fit an obvious migration pattern, for example:

  • Addition of an attribute

  • Removal of an attribute

  • A nonoptional attribute becoming optional

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

  • Renaming an entity or property

Managing Changes to Entities and Properties

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. Use the Xcode Data Modeling tool’s property inspector (for either an entity or a property) to set the renaming identifier in the managed object model. 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 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 in version 3. The renaming will work correctly going from version 2 to version 3, or from version 1 to version 3.

Managing Changes to Relationships

Lightweight migration can also manage changes to relationships and to the type of relationship. You can add a new relationship or delete an existing relationship. You can also rename a relationship by using a renaming identifier, just like an attribute.

In addition, you can change a relationship from a to-one to a to-many, or a nonordered to-many to an ordered (and vice versa).

Managing Changes to Hierarchies

You can add, remove, and rename entities in the hierarchy. You can also 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.

Confirming Whether Core Data Can Infer the Model

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

If your data change exceeds the capabilities of automatic migration, you can perform a heavyweight migration (often referred to as manual migration).

Requesting Lightweight Migration

You request automatic lightweight migration using the options dictionary that you pass into addPersistentStoreWithType:configuration:URL:options:error:. Set values corresponding to both the NSMigratePersistentStoresAutomaticallyOption and the NSInferMappingModelAutomaticallyOption keys to YES:

NSPersistentStoreCoordinator *psc = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel:mom];
NSDictionary *options = @{NSMigratePersistentStoresAutomaticallyOption: @YES, NSInferMappingModelAutomaticallyOption: @YES};
NSError *error = nil;
if (![psc addPersistentStoreWithType:NSSQLiteStoreType configuration:nil URL:storeURL options:options error:&error]) {
    NSAssert(NO, @"Unable to load persistent store: %@\n%@", [error localizedDescription], [error userInfo]);

With these settings in place, Core Data will attempt a lightweight migration when it detects the persistent store no longer matches the current model.

See Also

Data Migration

Heavyweight Migration

Use heavyweight (manual) migration in rare cases when changes to the data model exceed the capabilities of lightweight migration.