In a previous article, I talked about the feared Core Data error, "The model used to open the store is incompatible". As I said at the time, it comes about when you've been running a Core Data program, then you go back and make a change to the underlying Data Model.
This is easy enough to fix when you're in development mode. As long as you don't care about losing the data you've entered into your program through use, just delete it on your testing device or in the Simulator by touching the app, waiting for it to shimmer, then hitting the "X". When you recompile, everything will work fine.
However, you can't do that once a program has been released. Fortunately, Core Data includes migration tools to help you get the database in your live program upgraded to match the updated model in your source. And, if you've made simple Model changes, the migration is called "lightweight", which means that it's almost entirely painless--as long as you know what you're doing, and this article should make sure you do.
Here's what you'll need to do:
1. Verify that you can use lightweight migration.
You can only use lightweight migration if you're doing a simple, obvious change to your data model. Fortunately, that includes adding a relationship or an attribute, and that's exactly what you'll be doing most of the time.
If you want to do more, that's beyond the scope of this article, but you can read the Apple Documentation.
2. Add a new model version.
Click on your data model, then choose "Design > Data Model > Add Model Version". Where you previously had an "xcdatamodel" file, you should now see an "xcdatamodeld" folder that contains your original "xcdatamodel", plus a new copy of it numbered with a "2".
For example, my "Money.xcdatamodel" was put into the "Money.xcdatamodeld" folder and cloned as "Money 2.xcdatamodel", as shown in the picture below.
3. Make your changes.
You should not have made any changes prior to adding that new model version. If you did, this upgrade will NOT work.
Now that you've created a new model version, you should edit the new one, adding the attributions, relationships, or other simple updates that you want.
4. Change your current verison.
When you're all done, click on the new version, then select "Design > Data Model > Set Current Version". This will make it so that the new, updated version of your model is now the one being used by program.
5. Update your persistentStoreCoordinator call.
By default, Xcode should have created a persisentStoreCoordinator method for you when you created your project. You now need to modify that by adding two options which tell the coordinator to attempt a lightweight migration whenever it's run.
Here's the updated coordinator, from my Money program:
- (NSPersistentStoreCoordinator *)persistentStoreCoordinator {If you compare that to the original, you'll see two notable changes. First,an options dictionary is created with two objects, then options is passed as an argument to addPersistentStoreWithType: ...
if (persistentStoreCoordinator != nil) {
return persistentStoreCoordinator;
}
NSURL *storeUrl = [NSURL fileURLWithPath: [[self applicationDocumentsDirectory] stringByAppendingPathComponent: @"Money.sqlite"]];
NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys:
[NSNumber numberWithBool:YES],
NSMigratePersistentStoresAutomaticallyOption,
[NSNumber numberWithBool:YES],
NSInferMappingModelAutomaticallyOption,
nil];
NSError *error;
persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc]
initWithManagedObjectModel: [self managedObjectModel]];
if (![persistentStoreCoordinator addPersistentStoreWithType:NSSQLiteStoreType
configuration:nil URL:storeUrl options:options error:&error]) {
NSLog(@"Could Not Start Peristent Store: %@, %@", error, [error userInfo]);
}
return persistentStoreCoordinator;
}
5. Prefill Any Data
You may now need to prefill the new attribute or relationship you created, to make sure that your data content catches up with the new data field. Here's a sample of some code I used in my Money program:
-(void)upgradePath {
int upgradeV = [[cardDecks getOptionStringForKey:@"upgradeVersion"] intValue];
if (!upgradeV || upgradeV <= 1) {
int cardBackNum = [[cardDecks getOptionStringForKey:@"cardBack"] intValue];
NSString *thisBack = [self cardBackForInt:cardBackNum];
[cardDecks setCardBacks:thisBack forType:nil];
[cardDecks setOptionString:@"2" forKey:@"upgradeVersion"];
}
}
Most of these method calls are internal to my own program. However, the general philosophy should be quickly adaptable.
First, you want to maintain some variable (probably in Core Data) that keeps track of how far you've updated your data to match your database. Here, if a user skips this version, but then downloads the next which has another data content change, he'll still be back at "upgradeVersion" 1, and so the program will know to do the 2nd upgrade as well as any newer ones.
Second, you want to fill your new relationship or attribute with some rational information. In this case, I went off and I set the "cardBack" (which was my new relation) for the entire deck to a standard cardBack selected by the user in an option file.
Your Mileage Will Vary, but the core ideas will be similar.
6. Make clean.
Before you recompile, do a "Build > Clean All Targets". If you do not you may get the error, "Can't merge models with two different entities named 'Whatever'", followed by an annoying crash.
Conclusion
Once you've done a lightweight migration once, it should be simple and stress-free in the future. Just follow the same procedures.