2018第一篇技术文章，之前写过一篇关于CoreData基础的文章Magical Record 全面解析。关于CoreData迁移相关的文章网上有一些，但是都不是特别全面，所以这里总结一下，一方面自己巩固，一方面希望能帮到需要的同学。

CoreData迁移主要是两个方面，一个是数据库版本迁移，一个是数据迁移。

Migration is required when the model doesn't match the store.

首先推荐一个应用内调试的工具FLEX，可以直接查看数据库文件。

CoreData数据库版本迁移

数据库版本迁移比较简单。一般情况下是在新增了一张表之后，更新一下数据文件。

选中xcdatamodel文件之后，点击editor。可以看到如下选项。

。

这里包含了关于xcdatamodel大部分操作。选择Add Model Version。

完成之后可以看到

选中其中一个xcdatamodel文件，查看文件属性。这里包含了xcdatamodel各种属性，值得注意的是有个langua和coredatamodel，这两个后面会用到。

选择当前版本为新建的版本既可以了。完成之后小绿勾就会显示在更改的版本上。

CoreData数据迁移

凡是会引起NSManagedObjectModel托管对象模型变化的，都最好进行数据迁移，防止用户升级应用之后就闪退。会引起NSManagedObjectModel托管对象模型变化的有以下几个操作，新增了一张表，新增了一张表里面的一个实体，新增一个实体的一个属性，把一个实体的某个属性迁移到另外一个实体的某个属性里面等等

轻量级迁移

能够通过自动推断的迁移叫做轻量级迁移。如果只是做了很小的改变，比如给实体新增了属性，CoreData能够根据自动推断做自动数据迁移。轻量级迁移与普通迁移基本相同，不同之处在于我们自己不用提供映射模型（ mapping model）。

如下场景可以使用轻量级迁移：

简单的新增、删除属性
重命名实体、属性
属性的可选与不可选之间的变化
可选变为不可选，并且定义了默认值。

特别注意，如果改变属性类型，CoreData不能自动推断，也就不是轻量级迁移。

轻量级迁移代码如下：

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.
}

经过Demo测试可以总结出

如果不用自动迁移则会出现如下现象：

实体名字的修改会把之前的保存数据删除，原实体表删除。
属性名称的修改之后保存数据全部删除。

开启自动迁移则会：

实体名字的修改会把之前的保存数据删除，原实体表删除。
属性名称的修改之后数据能够成功迁移过来。

顺便提一下，magicRecord只提供了轻量级迁移的方式。

那么怎么判断CoreData是否可以进行自动迁移呢（其实所有的迁移都是都过NSMappingModel实现的，自动迁移也就是自动生成了NSMappingModel而已)。可以自定义，通过如下方法，分别传入源store，和目标store实现。

- (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;
}

如果使用了MagicRecord，可以使用 [MagicalRecord setupAutoMigratingCoreDataStack]一行代码实现轻量级迁移。

重量级迁移

如果CoreData不能自动推断，就需要用稍微复杂的防护四去迁移数据。原理就是需要定义怎么去转换数据，所有的信息包含在映射模型中，映射模型是一系列迁移信息的集合。上面提到的轻量级迁移是通过自动生成NSMappingModel实现的，重量级迁移需要我们自己去创建NSMappingModel。Xcode提供了可视化的工具来创建映射模型。

常见对象

类比对象模型，CoreData提供了针对，模型，实体，属性的迁移工具(NSMappingModel, NSEntityMapping, 和 NSPropertyMapping).。

NSMappingModel：包含了NSEntityMapping，NSPropertyMapping的映射模型
NSEntityMapping：包含源实体，目标实体还有映射的类型（新增，移除，拷贝，或者转换）
NSPropertyMapping：包含在源实体和目标实体的名称，和一个表达式值。

除此之外还提供了自定义的方式。

可以在在Xcode的属性面板上直接使用自定义的表达式来做简单的迁移（复杂的迁移也是基于这些表达式）。

迁移从一个属性到另一个属性：比如amount属性重命名为totalCost。输入表达式$source.amount。
转换值：比如由temperature华氏摄氏度到摄氏度，表达式($source.temperature - 32.0) / 1.8.

一共有有6个预定义的key.

NSMigrationManagerKey: $manager

NSMigrationSourceObjectKey: $source

NSMigrationDestinationObjectKey: $destination

NSMigrationEntityMappingKey: $entityMapping

NSMigrationPropertyMappingKey: $propertyMapping

NSMigrationEntityPolicyKey: $entityPolicy

通过Xcode创建映射模型

这里以一个Student实体为例
先插入数据，便于查看变化：

 [[NSManagedObjectContext MR_defaultContext] MR_saveWithBlock:^(NSManagedObjectContext * _Nonnull localContext) {
        for (int i = 0; i < 100; i++) {
            Student *sdt = [Student MR_createEntityInContext:localContext];
            sdt.name = [NSString stringWithFormat:@"sdt_%d",i];
            sdt.age = @(i);
        }
    } completion:^(BOOL contextDidSave, NSError * _Nullable error) {
        if (contextDidSave) {
            NSLog(@"Save Success");
        }
    }];

创建新的xcdatamodel文件

新建两个实体用于迁移Student中的age，name属性

新建映射模型文件，并且选择源和目的xcdatamodel：

创建完之后可以看到

这里的$source.age和上面介绍得输入表达式一样。可以使用上面预定义的6个key

需要特别注意一下下面的这个部分，迁移的规则都是从这里设置的

设置好source和destination

迁移的工作到这里就基本完成了，最后设置一下当前xcdatamodel文件的版。然后跑起来就可以在最新的数据库文件里面看到如下结果：

确实多了两张表

三张表的内容如下

数据确实从Student表里面迁移到了StudentAge表和StudentName表。

代码数据迁移

通过上面可视化的操作已经可以达到迁移的目的了，通过代码进行迁移主要是在数据迁移过程中，如果你还想做一些什么其他事情，比如说你想清理一下垃圾数据，实时展示数据迁移的进度。

直接上代码

检测是否需要迁移：

- (BOOL)isMigrationNecessaryForStore:(NSURL*)storeUrl
{
    NSLog(@"Running %@ '%@'", self.class, NSStringFromSelector(_cmd));
    
    if (![[NSFileManager defaultManager] fileExistsAtPath:[self storeURL].path])
    {
        NSLog(@"SKIPPED MIGRATION: Source database missing.");
        return NO;
    }
    
    NSError *error = nil;
    NSDictionary *sourceMetadata =
    [NSPersistentStoreCoordinator metadataForPersistentStoreOfType:NSSQLiteStoreType
                                                               URL:storeUrl error:&error];
    NSManagedObjectModel *destinationModel = _coordinator.managedObjectModel;
    
    if ([destinationModel isConfiguration:nil compatibleWithStoreMetadata:sourceMetadata])
    {
        NSLog(@"SKIPPED MIGRATION: Source is already compatible");
        return NO;
    }
    
    return YES;
}

如何进行迁移：

- (BOOL)migrateStore:(NSURL*)sourceStore {
    
    NSLog(@"Running %@ '%@'", self.class, NSStringFromSelector(_cmd));
    BOOL success = NO;
    NSError *error = nil;
    
    // STEP 1 - 收集 Source源实体, Destination目标实体 和 Mapping Model文件
    NSDictionary *sourceMetadata = [NSPersistentStoreCoordinator
                                    metadataForPersistentStoreOfType:NSSQLiteStoreType
                                    URL:sourceStore
                                    error:&error];
    
    NSManagedObjectModel *sourceModel =
    [NSManagedObjectModel mergedModelFromBundles:nil
                                forStoreMetadata:sourceMetadata];
    
    NSManagedObjectModel *destinModel = _model;
    
    NSMappingModel *mappingModel =
    [NSMappingModel mappingModelFromBundles:nil
                             forSourceModel:sourceModel
                           destinationModel:destinModel];
    
    // STEP 2 - 开始执行 migration合并, 前提是 mapping model 不是空，或者存在
    if (mappingModel) {
        NSError *error = nil;
        NSMigrationManager *migrationManager =
        [[NSMigrationManager alloc] initWithSourceModel:sourceModel
                                       destinationModel:destinModel];
        [migrationManager addObserver:self
                           forKeyPath:@"migrationProgress"
                              options:NSKeyValueObservingOptionNew
                              context:NULL];
NSURL *destinStore =
        [[self applicationStoresDirectory]
         URLByAppendingPathComponent:@"Temp.sqlite"];
        
        success =
        [migrationManager migrateStoreFromURL:sourceStore
                                         type:NSSQLiteStoreType options:nil
                             withMappingModel:mappingModel
                             toDestinationURL:destinStore
                              destinationType:NSSQLiteStoreType
                           destinationOptions:nil
                                        error:&error];
        if (success)
        {
            // STEP 3 - 用新的migrated store替换老的store
            if ([self replaceStore:sourceStore withStore:destinStore])
            {
                NSLog(@"SUCCESSFULLY MIGRATED %@ to the Current Model",
                          sourceStore.path);
                [migrationManager removeObserver:self
                                      forKeyPath:@"migrationProgress"];
            }
        }
        else
        {
            NSLog(@"FAILED MIGRATION: %@",error);
        }
    }
    else
    {
        NSLog(@"FAILED MIGRATION: Mapping Model is null");
    }
    
    return YES; // migration已经完成
}

迁移进度有变化，会通过观察者，observeValueForKeyPath来告诉用户进度，这里可以监听该进度，如果没有完成，可以来禁止用户执行某些操作。

- (void)observeValueForKeyPath:(NSString *)keyPath
                      ofObject:(id)object
                        change:(NSDictionary *)change
                       context:(void *)context {
    
    if ([keyPath isEqualToString:@"migrationProgress"]) {
        
        dispatch_async(dispatch_get_main_queue(), ^{
            
            float progress =
            [[change objectForKey:NSKeyValueChangeNewKey] floatValue];
          
            int percentage = progress * 100;
            NSString *string =
            [NSString stringWithFormat:@"Migration Progress: %i%%",
             percentage];
            NSLog(@"%@",string);

        });
    }
}

代码迁移这块，读者可以自己试一试。

扩展阅读

Wha Is Core Data?
Next Core Data Model Versioning and Data Migration
iOS Core Data 数据迁移指南

CoreDara版本迁移、数据迁移