Skill v1.0.1
currentAutomated scan95/100+2 new
version: "1.0.1" name: core-data description: "Build, review, or improve Core Data persistence in apps that have not adopted SwiftData. Use when working with NSManagedObject subclasses, NSFetchedResultsController for list-driven UI, NSBatchInsertRequest / NSBatchDeleteRequest / NSBatchUpdateRequest for bulk operations, NSPersistentHistoryChangeRequest for persistent history tracking and multi-target sync, NSStagedMigrationManager for staged schema migrations (iOS 17+), NSCompositeAttributeDescription for composite attributes (iOS 17+), or when integrating Core Data threading with Swift Concurrency. For Core Data + SwiftData coexistence or migration, see the swiftdata skill instead."
Core Data
Build and maintain data persistence using Core Data for apps that have not adopted SwiftData. Covers stack setup, concurrency, batch operations, NSFetchedResultsController, persistent history tracking, staged migration, and testing.
Contents
- Stack Setup
- Concurrency and Threading
- NSFetchedResultsController
- Batch Operations
- Persistent History Tracking
- Staged Migration
- Composite Attributes
- SwiftData Boundary
- Testing
- Common Mistakes
- Review Checklist
- References
Stack Setup
NSPersistentContainer encapsulates the Core Data stack.
Docs: NSPersistentContainer
import CoreDatafinal class CoreDataStack: @unchecked Sendable {static let shared = CoreDataStack()let container: NSPersistentContainerprivate init() {container = NSPersistentContainer(name: "MyAppModel")container.loadPersistentStores { _, error inif let error { fatalError("Core Data store failed: \(error)") }}container.viewContext.automaticallyMergesChangesFromParent = truecontainer.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy}var viewContext: NSManagedObjectContext { container.viewContext }func newBackgroundContext() -> NSManagedObjectContext {container.newBackgroundContext()}}
For CloudKit sync, use NSPersistentCloudKitContainer instead.
Concurrency and Threading
Core Data contexts are bound to queues. The viewContext is on the main queue; background contexts operate on private queues.
Docs: NSManagedObjectContext
Rules:
- Always use
perform(_:)orperformAndWait(_:)when accessing a context
off its own queue.
- Never pass
NSManagedObjectinstances across context or thread boundaries.
Pass NSManagedObjectID instead and re-fetch.
- Set
automaticallyMergesChangesFromParent = trueon theviewContext.
// Writing on a background contextfunc updateTrip(id: NSManagedObjectID, newName: String) async throws {let context = CoreDataStack.shared.newBackgroundContext()try await context.perform {guard let trip = try context.existingObject(with: id) as? CDTrip else {throw PersistenceError.notFound}trip.name = newNametry context.save()}}
Swift Concurrency Integration
NSManagedObjectContext.perform(_:) has an async throws overload (iOS 15+). Avoid marking NSManagedObject subclasses as Sendable.
func importItems(_ records: [ItemRecord]) async throws {let context = CoreDataStack.shared.newBackgroundContext()try await context.perform {for record in records {let item = CDItem(context: context)item.id = record.iditem.title = record.title}try context.save()}// After save completes, viewContext auto-merges if configured}
Do not use `@unchecked Sendable` on managed objects. If you need cross-boundary communication, pass the objectID (which is Sendable) and re-fetch:
let objectID = trip.objectID // SendableTask.detached {let bgContext = CoreDataStack.shared.newBackgroundContext()try await bgContext.perform {let trip = try bgContext.existingObject(with: objectID) as! CDTriptrip.isFavorite = truetry bgContext.save()}}
NSFetchedResultsController
Efficiently drives UITableView / UICollectionView from a Core Data fetch request, with built-in change tracking and optional caching.
Docs: NSFetchedResultsController
import CoreDataimport UIKitclass TripsViewController: UITableViewController, NSFetchedResultsControllerDelegate {private lazy var fetchedResultsController: NSFetchedResultsController<CDTrip> = {let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()request.sortDescriptors = [NSSortDescriptor(keyPath: \CDTrip.startDate, ascending: false)]request.fetchBatchSize = 20let controller = NSFetchedResultsController(fetchRequest: request,managedObjectContext: CoreDataStack.shared.viewContext,sectionNameKeyPath: nil,cacheName: "TripsCache")controller.delegate = selfreturn controller}()override func viewDidLoad() {super.viewDidLoad()try? fetchedResultsController.performFetch()}// MARK: - UITableViewDataSourceoverride func numberOfSections(in tableView: UITableView) -> Int {fetchedResultsController.sections?.count ?? 0}override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {fetchedResultsController.sections?[section].numberOfObjects ?? 0}override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {let cell = tableView.dequeueReusableCell(withIdentifier: "TripCell", for: indexPath)let trip = fetchedResultsController.object(at: indexPath)cell.textLabel?.text = trip.namereturn cell}// MARK: - NSFetchedResultsControllerDelegate (diffable)func controller(_ controller: NSFetchedResultsController<any NSFetchRequestResult>,didChangeContentWith snapshot: NSDiffableDataSourceSnapshotReference) {let snapshot = snapshot as NSDiffableDataSourceSnapshot<String, NSManagedObjectID>dataSource.apply(snapshot, animatingDifferences: true)}}
Key points:
- The fetch request must have at least one sort descriptor.
- Call
deleteCache(withName:)before changing the fetch request predicate or
sort descriptors, or set cacheName to nil.
- The diffable snapshot delegate method (
didChangeContentWith:) is available
iOS 13+ and is preferred over the older per-change callbacks.
- After a context
reset(), callperformFetch()again.
Batch Operations
Batch operations execute at the SQL level, bypassing the managed object context. They are fast but don't trigger context notifications automatically.
NSBatchInsertRequest (iOS 13+)
Docs: NSBatchInsertRequest
func batchImport(_ records: [[String: Any]]) async throws {let context = CoreDataStack.shared.newBackgroundContext()try await context.perform {let request = NSBatchInsertRequest(entity: CDTrip.entity(),objects: records)request.resultType = .objectIDslet result = try context.execute(request) as? NSBatchInsertResultif let ids = result?.result as? [NSManagedObjectID] {NSManagedObjectContext.mergeChanges(fromRemoteContextSave: [NSInsertedObjectsKey: ids],into: [CoreDataStack.shared.viewContext])}}}
NSBatchDeleteRequest (iOS 9+)
Docs: NSBatchDeleteRequest
func deleteOldTrips(before cutoff: Date) async throws {let context = CoreDataStack.shared.newBackgroundContext()try await context.perform {let fetchRequest: NSFetchRequest<NSFetchRequestResult> = CDTrip.fetchRequest()fetchRequest.predicate = NSPredicate(format: "endDate < %@", cutoff as NSDate)let request = NSBatchDeleteRequest(fetchRequest: fetchRequest)request.resultType = .resultTypeObjectIDslet result = try context.execute(request) as? NSBatchDeleteResultif let ids = result?.result as? [NSManagedObjectID] {NSManagedObjectContext.mergeChanges(fromRemoteContextSave: [NSDeletedObjectsKey: ids],into: [CoreDataStack.shared.viewContext])}}}
NSBatchUpdateRequest (iOS 8+)
func markAllTripsAsNotFavorite() async throws {let context = CoreDataStack.shared.newBackgroundContext()try await context.perform {let request = NSBatchUpdateRequest(entity: CDTrip.entity())request.propertiesToUpdate = ["isFavorite": false]request.resultType = .updatedObjectIDsResultTypelet result = try context.execute(request) as? NSBatchUpdateResultif let ids = result?.result as? [NSManagedObjectID] {NSManagedObjectContext.mergeChanges(fromRemoteContextSave: [NSUpdatedObjectsKey: ids],into: [CoreDataStack.shared.viewContext])}}}
Always merge changes back into relevant contexts after batch operations. Batch delete does not enforce the Deny delete rule.
Persistent History Tracking
Track store-level changes across targets (app, extensions, widgets) and processes.
Docs: NSPersistentHistoryChangeRequest
Enable History Tracking
let description = NSPersistentStoreDescription()description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)description.setOption(true as NSNumber,forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)container.persistentStoreDescriptions = [description]
Observe, Fetch, Merge, and Purge
// 1. Observe remote change notificationsNotificationCenter.default.addObserver(self, selector: #selector(storeRemoteChange(_:)),name: .NSPersistentStoreRemoteChange, object: container.persistentStoreCoordinator)// 2. Fetch history since last token@objc func storeRemoteChange(_ notification: Notification) {let context = container.newBackgroundContext()context.perform {let request = NSPersistentHistoryChangeRequest.fetchHistory(after: self.lastToken)if let result = try? context.execute(request) as? NSPersistentHistoryResult,let transactions = result.result as? [NSPersistentHistoryTransaction] {// 3. Merge into viewContextfor transaction in transactions {self.container.viewContext.mergeChanges(fromContextDidSave: transaction.objectIDNotification())self.lastToken = transaction.token}}// 4. Purge old historylet purgeRequest = NSPersistentHistoryChangeRequest.deleteHistory(before: self.lastToken)try? context.execute(purgeRequest)}}
Store lastToken in UserDefaults (per target) so history is processed correctly across launches.
Staged Migration
NSStagedMigrationManager (iOS 17+) sequences schema migrations through ordered stages, each lightweight or custom.
Docs: NSStagedMigrationManager
import CoreData// Define migration stages// Use version checksums from the compiled model versions, not model names.let checksumV1 = "<ModelV1 version checksum>"let checksumV2 = "<ModelV2 version checksum>"let checksumV3 = "<ModelV3 version checksum>"let stage1to2 = NSLightweightMigrationStage([checksumV1, checksumV2])stage1to2.label = "Add isFavorite property"let modelV2 = NSManagedObjectModelReference(name: "ModelV2",in: Bundle.main,versionChecksum: checksumV2)let modelV3 = NSManagedObjectModelReference(name: "ModelV3",in: Bundle.main,versionChecksum: checksumV3)let stage2to3 = NSCustomMigrationStage(migratingFrom: modelV2,to: modelV3)stage2to3.label = "Split name into firstName/lastName"stage2to3.willMigrateHandler = { migrationManager, currentStage inguard let container = migrationManager.container else { return }let context = container.newBackgroundContext()try context.performAndWait {// Transform data between schema versionslet request = NSFetchRequest<NSManagedObject>(entityName: "Person")let people = try context.fetch(request)for person in people {let fullName = person.value(forKey: "name") as? String ?? ""let parts = fullName.split(separator: " ", maxSplits: 1)person.setValue(String(parts.first ?? ""), forKey: "firstName")person.setValue(parts.count > 1 ? String(parts.last!) : "", forKey: "lastName")}try context.save()}}// Apply to the persistent storelet manager = NSStagedMigrationManager([stage1to2, stage2to3])let description = NSPersistentStoreDescription()description.setOption(manager,forKey: NSPersistentStoreStagedMigrationManagerOptionKey)container.persistentStoreDescriptions = [description]container.loadPersistentStores { _, error inif let error { fatalError("Migration failed: \(error)") }}
For apps targeting below iOS 17, use lightweight migration (NSInferMappingModelAutomaticallyOption) or mapping models.
NSLightweightMigrationStage takes version checksums ([String]), not human-readable model names.
Composite Attributes
iOS 17+ supports composite attributes: groups of sub-attributes on an entity that act as a single logical unit. Define them in the model editor by adding a Composite type attribute and nesting sub-attributes beneath it.
Docs: NSCompositeAttributeDescription
Composite attributes map to Codable structs in SwiftData coexistence scenarios.
SwiftData Boundary
Use the swiftdata skill for Core Data + SwiftData coexistence or migration implementation. Before handing off, preserve these Core Data boundaries:
- SwiftData must point at the existing persistent store URL when it is meant to
share or migrate Core Data data.
- Shared persisted data must keep entity names, property names, types, and
schema compatible across the Core Data model and SwiftData @Model classes.
- Map renamed persisted properties with SwiftData
@Attribute(originalName:).
Testing
In-Memory Store for Tests
import CoreDataimport Testingstruct CoreDataTests {func makeTestContainer() throws -> NSPersistentContainer {let container = NSPersistentContainer(name: "MyAppModel")let description = NSPersistentStoreDescription()description.type = NSInMemoryStoreTypecontainer.persistentStoreDescriptions = [description]var loadError: Error?container.loadPersistentStores { _, error in loadError = error }if let loadError { throw loadError }return container}@Test func createAndFetchTrip() throws {let container = try makeTestContainer()let context = container.viewContextlet trip = CDTrip(context: context)trip.name = "Test Trip"trip.startDate = .nowtry context.save()let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()let trips = try context.fetch(request)#expect(trips.count == 1)#expect(trips.first?.name == "Test Trip")}}
Tips:
- Share the
NSManagedObjectModelinstance across tests to avoid "duplicate
entity" warnings.
- Use a single shared model loaded once:
private let sharedModel: NSManagedObjectModel = {let url = Bundle.main.url(forResource: "MyAppModel", withExtension: "momd")!return NSManagedObjectModel(contentsOf: url)!}()func makeTestContainer() throws -> NSPersistentContainer {let container = NSPersistentContainer(name: "MyAppModel",managedObjectModel: sharedModel)// ... configure in-memory store}
Common Mistakes
| Mistake | Fix | |
|---|---|---|
Passing NSManagedObject across threads | Pass objectID and re-fetch in the target context | |
| Forgetting to merge batch operation results | Call mergeChanges(fromRemoteContextSave:into:) | |
Calling save() without checking hasChanges | Guard with context.hasChanges first | |
Using deprecated init(concurrencyType:) confinement type | Use .privateQueueConcurrencyType or .mainQueueConcurrencyType | |
Not setting mergePolicy on viewContext | Set NSMergeByPropertyObjectTrumpMergePolicy to avoid conflict crashes | |
Modifying fetch request on live NSFetchedResultsController without deleting cache | Call deleteCache(withName:) first or use cacheName: nil | |
| Batch delete ignoring Deny delete rule | Batch delete bypasses delete rules; validate manually | |
Marking NSManagedObject as @unchecked Sendable | Do not. Pass objectID instead | |
| Pointing SwiftData at a fresh store during coexistence | Use the existing store URL and compatible schema when SwiftData should share or migrate Core Data data |
Review Checklist
- [ ]
NSPersistentContaineris initialized once and shared - [ ]
viewContextused only on main queue; background contexts for writes - [ ]
perform(_:)orperformAndWait(_:)wraps all off-queue context access - [ ]
automaticallyMergesChangesFromParentset onviewContext - [ ]
mergePolicyset onviewContextto prevent conflict crashes - [ ] Batch operation results merged into relevant contexts
- [ ]
NSFetchedResultsControllerfetch requests have sort descriptors - [ ] Persistent history tracking enabled for multi-target apps
- [ ] Core Data + SwiftData handoff preserves store URL, schema compatibility, entity/property names, and rename mappings
- [ ] Tests use in-memory stores with shared
NSManagedObjectModel - [ ] No
NSManagedObjectinstances cross thread boundaries
References
- Apple docs: Core Data | NSPersistentContainer | NSFetchedResultsController | NSStagedMigrationManager