[iOS] Core Data 자동 마이그레이션 적용 방법

Core Data 모델을 수정하면 앱이 크래시가 발생하는 경우가 있다.

이유는 Core Data의 데이터 모델이 변경될 때, 기존 데이터와 호환되지 않기 때문이다.

이를 해결하기 위해 자동 마이그레이션을 적용하는 방법을 정리한다.

문제 상황

Core Data 모델에 새로운 속성을 추가한 후 앱을 실행하자 아래와 같은 오류가 발생했다.

Error Domain=NSCocoaErrorDomain Code=134140 "Persistent store migration failed"

이 오류는 Core Data가 기존 데이터 모델과 새로운 데이터 모델 간의 변경 사항을 인식하지 못했기 때문에 발생했다.

해결 방안

Core Data에는 lightweight migration이라는 자동 마이그레이션 기능이 있다.

이 기능을 활성화하면 기본적인 모델 변경(속성 추가, 삭제 등)은 자동으로 처리된다.

1. NSPersistentContainer에서 자동 마이그레이션 옵션 활성화

   • Core Data에서 NSPersistentContainer를 사용할 경우, 자동 마이그레이션 옵션을 추가하면 해결된다.

   • shouldMigrateStoreAutomatically = true → Core Data가 기본적인 변경을 자동 처리하도록 설정

   • shouldInferMappingModelAutomatically = true → 속성 추가/삭제 등의 단순 변경을 Core Data가 자동 감지

   import CoreData
   
   class CoreDataManager {
       static let shared = CoreDataManager()
   
       lazy var persistentContainer: NSPersistentContainer = {
           let container = NSPersistentContainer(name: "MyAppModel")
   
           let description = container.persistentStoreDescriptions.first
           description?.shouldMigrateStoreAutomatically = true
           description?.shouldInferMappingModelAutomatically = true
   
           container.loadPersistentStores { _, error in
               if let error = error {
                   fatalError("Unresolved error: \(error)")
               }
           }
           
           return container
       }()
   
       var context: NSManagedObjectContext {
           return persistentContainer.viewContext
       }
   }

2. (필요 시) 데이터 모델 버전 관리 적용

   • 위 설정을 적용해도 해결되지 않는다면, 데이터 모델의 버전을 명시적으로 관리해야 한다.

     1. xcdatamodeld 파일을 선택

     2. Editor → Add Model Version 클릭

     3. 새로운 모델 버전을 만들고, 변경 사항을 적용

     4. Current Model을 새로운 버전으로 변경