Database Migration for IOS App: Best Practices

For an iOS application developer, iOS app database migration is something that will be done sooner or later. It happens to all popular apps that are actively maintained and regularly updated.

Imagine you are working on iOS application that stores a list of user’s contacts. In the first version of the app, contact information was stored in the form of this structure: {NSString *fullName; NSUInteger identifier} (see left diagram in the picture). The first version was released early and immediately published in the AppStore to collect feedback and adjust the future development goals.

Soon the design changes and we no longer store identifier in an NSUInteger variable. Besides, the name of a contact is now represented as two strings (see right diagram in the picture). All three attributes are strings now.

Of course, now we have to decide how to treat the existing users who are already storing some contacts in the installed app. Automatic iOS app database migration is not going to help here, because it is unable to convert an NSNumber (number with NSUIntger) to string, not to mention the change to fullName field.

The first solution is to simply delete the old database and create a new one from scratch using the new model. The second solution, which the users will actually prefer, is to implement data migration to the new version. So let’s talk about implementing migration in more detail here.

First we need to create a Mapping Model (New File > Core Data > Mapping Model). Choose the first version of your model as the source model and the second version as the destination.

Next, we need to subclass NSEntityMigrationPolicy and redefine the following method:

createDestinationInstancesForSourceInstance:entityMapping:manager:error:

For our example case the method is going to look like below:

- (BOOL)createDestinationInstancesForSourceInstance:(NSManagedObject *)sInstance entityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error 
{ 
 NSManagedObject *newObject = [NSEntityDescription insertNewObjectForEntityForName:[mapping destinationEntityName] inManagedObjectContext:[manager destinationContext]]; 
 
 NSString *fullName = [sInstance valueForKey:@"fullName"]; 
 NSArray *nameComponentsArray = [fullName componentsSeparatedByString:@" "]; 
NSString *lastName = [nameComponentsArray lastObject]; 
NSString *firstName = [nameComponentsArray[0]; 
 
 [newObject setValue:firstName forKey:@"firstName"]; 
 [newObject setValue:lastName forKey:@"lastName"]; 
 
 [manager associateSourceInstance:sInstance withDestinationInstance:newObject forEntityMapping:mapping]; 
 
 return YES; 
}

There is no need to implement migration for every object by hand, only for those that fail to auto-migrate. The Mapping Model describes which classes should be processed by custom migration code, and which should be migrated automatically. If the automatic migration will not work, it is possible to change the migration policy later in the migration mapping editor.

In a really complex situation, like several different model versions with different migration logic, you can add version identifiers to the function above and specify as many migration algorithms as required.

The following method may be used to open a model:

+ (NSManagedObjectModel *)mergedModelFromBundles:(NSArray *)bundles forStoreMetadata:(NSDictionary *)metadata.

But it will work only if your project has a single data model. If you are updating more than one model, use the following method.

Let’s assume the model we’re working on is called “dataModel”.

NSURL *dstStoreURL = [[NSBundle mainBundle] URLForResource:@"dataModel.momd" withExtension:nil]; 
 
 NSManagedObjectModel *model = [[NSManagedObjectModel alloc] initWithContentsOfURL:dstStoreURL];

Let’s create a coordinator to interact with the model database:

NSPersistentStoreCoordinator *coordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel:model]; 
 
 NSError *error = nil;

Next we need to copy the old database model with the new name and delete the original one:

NSFileManager * fileManager = [[NSFileManager alloc] init]; 
 
 NSArray *paths = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory,NSUserDomainMask, YES); 
 NSString *documentsDirectory = [paths objectAtIndex:0]; 
 NSString *documentDBFolderPath = [documentsDirectory stringByAppendingPathComponent:@"Application Support/PROJECT_NAME/dataModel.sqlite"]; 
 
 NSURL *storeFileURL = [NSURL fileURLWithPath:documentDBFolderPath]; 
 
 NSMutableString *url = [[NSMutableString alloc] initWithString:documentDBFolderPath]; 
 
 NSRange range = [url rangeOfString:storeFileName]; 
 
 if (range.location != NSNotFound) { 
 [url replaceCharactersInRange:range withString:@"newDataModel.sqlite"]; 
 } 
 
 NSURL *newStoreFileURL = [NSURL fileURLWithPath:url]; 
 [url release]; 
 
 [fileManager moveItemAtURL:storeFileURL toURL:newStoreFileURL error:&error ]; 
 
 error = nil;

NSURL *storeURL = [dstStoreURL URLByAppendingPathComponent:@"dataModel.mom"]; 
 
NSManagedObjectModel *sourceModel = [[NSManagedObjectModel alloc] initWithContentsOfURL:storeURL];

NSURL *migrationModelUrl = [[NSBundle mainBundle] URLForResource:@"ModelMigration" withExtension:@"cdm"]; 
 NSMappingModel *mappingModel = [[NSMappingModel alloc] initWithContentsOfURL:migrationModelUrl];

NSMigrationManager *manager = [[NSMigrationManager alloc] initWithSourceModel:sourceModel destinationModel:model];

error = nil; 

NSArray *newEntityMappings = [NSArray arrayWithArray:mappingModel.entityMappings]; 
 for (NSEntityMapping *entityMapping in newEntityMappings) { 
 [entityMapping setSourceEntityVersionHash:[sourceModel.entityVersionHashesByName valueForKey:entityMapping.sourceEntityName]]; 
 [entityMapping setDestinationEntityVersionHash:[model.entityVersionHashesByName valueForKey:entityMapping.destinationEntityName]]; 

 } 
 mappingModel.entityMappings = newEntityMappings;

Finally, the migration is executed by the following code:

BOOL result = [manager migrateStoreFromURL:newStoreFileURL type:NSSQLiteStoreType 
 options:nil withMappingModel:mappingModel toDestinationURL:storeFileURL 
 destinationType:NSSQLiteStoreType destinationOptions:nil error:&error];

In storeFileUrl we have the location of a new database, which we can now open using the new model.