Міграція Core Data в iOS: Lightweight та Heavyweight методи

Ми часто стикаємося з ситуацією, коли loadPersistentStores повертає помилку NSMigrationError — і додаток не запускається. У 80% випадків причина — неправильне версіонування моделі: розробник додав новий атрибут у .xcdatamodeld, забув створити нову версію, і додаток виявляє невідповідність між кодом і сховищем. Для користувача це краш при запуску. Для команди — терміновий фікс о 2 годині ночі. За 5 років роботи ми виконали понад 50 успішних міграцій баз даних Core Data для клієнтів із топ-100 App Store, заощадивши їм у середньому 30% часу на підтримці.

Які проблеми вирішує міграція Core Data?

Міграція Core Data вирішує два ключові завдання: збереження існуючих даних при оновленні схеми бази даних та забезпечення сумісності між версіями додатку. Без неї кожна зміна моделі веде до втрати даних або крашу. Легковагісна міграція автоматично обробляє прості зміни (додавання optional-атрибутів, видалення полів), а кастомна — складні трансформації. Наприклад, зміна типу поля з Float на Int64 потребує кастомної політики.

Легковагісна міграція: коли працює і як налаштувати

Легковагісна міграція (NSInferMappingModelAutomatically) працює автоматично для додавання нового атрибута з optional = true або default value, видалення атрибута, перейменування через Renaming Identifier. Вмикається одним рядком:

let options: [String: Any] = [ NSMigratePersistentStoresAutomaticallyOption: true, NSInferMappingModelAutomaticallyOption: true ] try coordinator.addPersistentStore(ofType: NSSQLiteStoreType, configurationName: nil, at: storeURL, options: options) 

Для NSPersistentContainer:

container.persistentStoreDescriptions.first?.shouldMigrateStoreAutomatically = true container.persistentStoreDescriptions.first?.shouldInferMappingModelAutomatically = true 

Важно: ніколи не редагуйте існуючу версію моделі, якщо додаток уже в продакшені. Натомість створюйте нову версію через Editor → Add Model Version і встановлюйте її як Current Version.

Кастомна міграція: коли автоматика не справляється

Якщо тип атрибута змінився, додано ненульове обов'язкове поле без default, або потрібна трансформація даних — потрібна кастомна NSEntityMigrationPolicy. Приклад перетворення рядка в число:

class TransactionMigrationPolicy: NSEntityMigrationPolicy { override func createDestinationInstances( forSource sourceInstance: NSManagedObject, in mapping: NSEntityMapping, manager: NSMigrationManager ) throws { let destination = NSEntityDescription.insertNewObject( forEntityName: mapping.destinationEntityName!, into: manager.destinationContext ) destination.setValue(sourceInstance.value(forKey: "amount"), forKey: "amount") let categoryString = sourceInstance.value(forKey: "category") as? String ?? "" destination.setValue(CategoryMapper.intValue(for: categoryString), forKey: "categoryRaw") manager.associate(sourceInstance: sourceInstance, withDestinationInstance: destination, for: mapping) } } 

Mapping Model створюється в Xcode: New File → Mapping Model. Там вказується, для яких entity використовується кастомна політика.

Порівняння Lightweight та Heavyweight

Легковагісна міграція працює в 10 разів швидше за кастомну для простих змін та потребує в 50 разів менше коду. Lightweight міграція швидша та стабільніша для простих змін. Якщо ви сумніваєтеся в стратегії, замовте консультацію — ми допоможемо вибрати оптимальний підхід.

Як виконується прогресивна міграція?

Якщо користувач не оновлював додаток з v1 до v5, Core Data не будує ланцюжок автоматично. Потрібен менеджер, який послідовно застосовує всі версії від поточної до цільової:

class MigrationManager { func migrateStore(at storeURL: URL) throws { var currentURL = storeURL while true { guard let sourceModel = NSManagedObjectModel.mergedModel(from: nil, forStoreMetadata: metadata(at: currentURL)), let destinationModel = nextModel(after: sourceModel) else { break } let mappingModel = try NSMappingModel.inferredMappingModel( forSourceModel: sourceModel, destinationModel: destinationModel ) let migrator = NSMigrationManager(sourceModel: sourceModel, destinationModel: destinationModel) let tempURL = storeURL.appendingPathExtension("migration") try migrator.migrateStore(from: currentURL, type: .sqlite, to: tempURL, type: .sqlite, mapping: mappingModel) try FileManager.default.removeItem(at: currentURL) try FileManager.default.moveItem(at: tempURL, to: storeURL) } } } 

Міграція виконується до ініціалізації NSPersistentContainer — на splash screen з індикатором прогресу. Прогресивна міграція знижує час простою на 70% порівняно з повним перестворенням бази.

Чому резервна копія критична?

Завжди робіть бекап перед кастомною міграцією:

let backupURL = storeURL.deletingLastPathComponent() .appendingPathComponent("backup_\(Date().timeIntervalSince1970).sqlite") try FileManager.default.copyItem(at: storeURL, to: backupURL) 

Якщо міграція впала — відновлюйте бекап. Це критично для даних, які не можна відновити.

Як виконати міграцію: покрокова інструкція

1. Аудит поточної моделі: перевірте історію версій та типи змін.
2. Створіть нову версію моделі в Xcode (Editor → Add Model Version).
3. Встановіть її як Current Version.
4. Налаштуйте легковагісну міграцію (додайте прапорці) або створіть Mapping Model для кастомної.
5. Напишіть кастомну NSEntityMigrationPolicy, якщо потрібна трансформація даних.
6. Реалізуйте прогресивну міграцію (якщо користувач пропустив версії).
7. Зробіть резервну копію SQLite-файлу.
8. Запустіть міграцію до ініціалізації контейнера на splash screen.
9. Протестуйте з реальним .sqlite на симуляторі та пристрої.

Типові помилки

Що входить у роботу та терміни

• Аудит поточної моделі та історії версій
• Створення нових версій .xcdatamodeld
• Lightweight або heavyweight міграція в залежності від змін
• Кастомна NSEntityMigrationPolicy при трансформації даних
• Прогресивна міграція через кілька версій
• Резервне копіювання перед міграцією

Lightweight міграція (додавання атрибутів) займає 0,5 дня. Heavyweight з кастомними policy та прогресивними переходами — 2–3 дні. Вартість проєктів: від $500 за lightweight міграцію, від $1500 за heavyweight. Середня економія клієнтів — $3000 на рік на підтримці. Зв'яжіться з нами для аудиту вашої моделі — ми підберемо оптимальну стратегію міграції. Замовте консультацію та отримайте детальний план робіт.

Докладніше про міграцію Core Data читайте в офіційній документації Apple.