Tutorial for NimbusBase iOS Migration

Lightweight Migration & Model Mapper

Lightweight migration is supported without any effort from the developer. All the migration information is inferred by NimbusBase base on the Managed Object Model (.momd or .mom file) and Mapping Model (.cdm file) in your app bundle.

Nevertheless, you can customize the migration process by offering a delegate, which is supposed to conform protocol NMBModelMapper, to NMBase when you initiate it. For example, if your Core Data assets are not in the main bundle, you can return the proper bundles in the method:

- (NSArray *)bundlesContainModelFilesContext:(id)context;

Or you prefer to map the entities in the historical Managed Object Model to the currently used version yourself, rather than let NimbusBase do that for you automatically, you can implement the following 2 methods:

- (NSPropertyDescription *)propertyNamed:(NSString *)name
                                ofEntity:(NSEntityDescription *)entity
                                 context:(id)context;
- (NSEntityDescription *)entityNamed:(NSString *)name
                             context:(id)context;

Custom Migration

You only need Custom migration when you want to initiate migration yourself. You might do this to, for example, perform a complicated model update, or deal with large data sets. It is supported by rebuild the database on cloud base on the local database, or right about. Instead of calling the method synchronize on NMBServer directly to trigger a sync, an options must be involved:

// Rebuild database on cloud base on local database
[self.server synchronizeWithOptions:@{NKeySyncCommitType:@(NMBSyncCommitTypePushEntirely)}];

// Or rebuild local database base on database on cloud
[self.server synchronizeWithOptions:@{NKeySyncCommitType:@(NMBSyncCommitTypePullEntirely)}];

If no option is passed during the first sync after a major migration, NimbusBase will detect the conflict and fail the sync with an error.

Once one of your device finishes the migration and the first sync after it, all of the other devices have to upgrade the app to the newest version before they can sync with the cloud. At this point, major migration behaves the same way with lightweight migration.

Besides, you need to announce the migration a major one in a NMBModelMapper’s method:

- (BOOL)isMigrationLightweightFromStore:(NSDictionary *)fromStoreMetadata
                                toStore:(NSDictionary *)toStoreMetadata
                                context:(id)context;

This method offers metadata of the source and destination NSPersistentStore related to the migration. And if you want it treated as a major migration, return NO.

Migration from iCloud

If you want to give up iCloud and choose NimbusBase to take charge of sync, that’s basically a major migration with Managed Object Model unmodified. The difference is migration from iCloud is auto-detected. No matter in the method mentioned above what kind you announce the migration belongs to, you need to rebuild the database. For detail, check our demo project NimbusBase iOS Tutorial.