"An in-depth discussion about standard migration is beyond the scope of this tutorial/book"

Ahem, who here is sick of seeing the above line when researching the disputed topic of Core Data Migration? You think you've found a solution for the nth time, only for nth example to deal exclusively with Lightweight migration. The translation of the above can read something like this:

"Standard migration steps and examples are erratically documented, and I can only be bothered to give an example on Lightweight migration, which in contrast has an endless supply of superbly documented steps and examples. Thus I can give the illusion of appearing smart and helpful, but really I can't be bothered explaining something that nobody else can either, because of it's extreme vagueness and complexity"

Well thanks for nothing lazy internet tutorial bloggers and authors (kidding, your free inaccurate work is much appreciated). I am only taking out my frustration because I have actually cracked the code! Finally, after spending months of my part time life trying to decipher Apple's Core Data Model Versioning and Data Migration Programming Guide about the order of steps involved, I have a successful working copy.

More importantly I'm motivated to share this piece of success in Internet-land, because nobody else has (as rare as it is in 2011 to not have every single topic in existence covered in some tutorial style, from "how to sew together my own football" to "how to create my own frankenstein monster and then teach it how to kick self-sewed football", this is proof there are still topics that have evaded the www space).

BACKGROUND:

Born out of the prospect of not wanting to have an app on the store that would instantly crash on start up the next time the user updated their app version, I hesitated changing the model. But I needed to. The app in it's current app store state is very limited and I needed to considerably expand the database. Because an expanded database would slow down the performance, and because the data had to be presented to the user in a more diverse fashion, my data model had to be normalised. I had to add new entities and new relationships, gasp.

Coming from a web programming background of LAMP and J2E, the concept of migration was confined to political discussions. If you changed your data model/schema in MySQL, you just programmed around it and it still worked. However, in the iOS and Mac Cocoa environment changing your model without versioning and migration results in a critical error, a crash, a titanic sinking…one which probably triggers a secret feedback response back to Apple that flashes on a neon lit screen so their army of knowledgable developers can gather around and share a chuckle, "Ha look, another idiot tried to change his model. We should really charge more for developer support".

Migration is a topic that's not so confusing to understand, but very confusing in how to figure out the best way to go about it. The lateral-thinking description in the Apple docs serves to only confuse more. Don't get me wrong, I'm a big fan of lateral-thinking solutions to achieve an outcome. This is fine to adopt for a work methodology. But where vertical-thinking is needed is actually in the description process. Apple do us no favours by having such erratically laid out descriptions of their frameworks.

The information out there is inconsistent and hard to grapple unless you see a full-scale working example. Excerpts that are presented in the Apple Core Data Model Versioning and Data Migration Programming Guide are scattered and incomplete. The major problem in the docs is that quite often, the order of where concepts are detailed, occur before a related preceding concept is explained.

CONCEPT:

Anyway, this digression isn't really important. What's important is how to achieve this! I finally understood the process of migration once i trawled through the docs for about the 10th time and graphically represented it as an Activity Diagram. This might need refinement (specifically the squished layout at the bottom), but this is the general process describing everything involved with Migration (Lightweight or Standard):

Yes activity diagrams, those things that we were taught in university but never use in the real world. It's kind of trendy to derail a lot of university teachings as being irrelevant, once you've graduated. But personally I find my lecturers were right about UML. Everything becomes clearer, and consequently 5 x faster to program, once I've detailed the design first. Every time, without fail.

This is a graphical representation of everything that's outlined in Apple's guide. The numbers below and in the diagram do NOT represent a chronological order! They purely just exist to link the graphics to the textual descriptions below. So to sum up what's going on here:

1)

• Check to see if a Model Version Identifier has been set in our data model. Core Data pays no attention to this in it's own version checking (it uses setVersionHashModifier:).
• This identifier has been set by you, the developer, to write your own condition to see if you even need to CHECK if the current store matches the current model.

2)

• If versioning is not supported and the current store is incompatible with the current model, and error is returned from the addPersistentStoreWithType method.

3)

• If versioning is supported and you only have a data model change that requires Lightweight Migration, set the key to infer automatic, inferred migration such as NSInferMappingModelAutomaticallyOption.
• Don't do anymore checks, just execute addPersistentStoreWithType and Core Data takes care of the rest.

4)

• If versioning is supported and you only have a data model change that requires Standard Migration, run a configuration check on the destination (current) model and the persistent source store.
• If the configuration is incompatible, a three stage migration is needed.
• Whether you need to make this "custom" (i.e. subclassing NSEntityMigrationPolicy) or not is entirely up to you, if you feel that you need to provide further validation on the new entities etc. You do not NEED to subclass NSEntityMigrationPolicy to achieve Standard migration!
• Create a new store for the current model
• Perform the migration between the old store and the new store with an instance of NSMigrationManager.

ACHIEVING STANDARD MIGRATION:

For lack of space I'll outline the actual steps on how to achieve Standard Migration in a "Part 2", which should be up within the next month at the time of writing this. We're going to use a real example, changing the model of a pre-existing Apple example project "iPhoneCoreDataRecipes".

So until then, TBC...