Core Data Migrations: Evolving Your App's Schema Safely

WHY IT EXISTS Apps evolve, and so do their data models. When you release a new version of your app with a different Core Data model, the existing user data on devices is stored in the old format. Without migration, the app would crash or fail to load the data, effectively losing it. Migrations bridge this gap, ensuring data from previous versions is compatible with the new one.

THE MENTAL MODEL Think of a Core Data migration as a translation script between two versions of your database schema. Core Data sees the old data file (schema v1) and knows it needs to match the app's new code (schema v2). The migration provides the step-by-step instructions to transform the v1 data into a v2-compatible format, preserving all the user's information.

HOW IT WORKS When your app starts, Core Data compares the schema of the persistent store file on disk with the schema compiled into your application. If they differ, it initiates a migration. 'Lightweight' migration is automatic; Core Data infers simple changes like adding a new attribute or renaming one (if you set its renaming identifier). For complex changes, you must create a 'heavyweight' migration using a Mapping Model (.xcmappingmodel) file. This file lets you define explicit transformation rules.

WHEN TO USE IT Use lightweight migration for simple changes: adding or removing an attribute, entity, or relationship; making an optional attribute non-optional (with a default value); or renaming an element. Use heavyweight (custom) migration for anything more complex, such as splitting an entity, merging entities, or transforming data values during the migration (e.g., converting a string to a number).

WHEN NOT TO USE IT You don't need migrations for an app's first release or if the data model will never change. The main footgun is attempting a change with lightweight migration that requires a heavyweight one. For example, changing an attribute's type from String to a custom Transformable type requires a custom mapping model. The migration will simply fail at runtime, potentially leading to data loss if not handled gracefully.

ONE CANONICAL EXAMPLE Your v1 app has a Note entity with a creationDate as a String. In v2, you change it to a Date type for better sorting. A lightweight migration will fail because Core Data doesn't know how to parse the string into a date. You must create a custom migration with a mapping model that specifies how to transform the source string into the destination Date object, likely using a custom entity migration policy class.