Core Data

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

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.

Instructions onlySoftware Development

AI-generated overview

Guides building, reviewing, and improving Core Data persistence in Apple apps, covering stack setup, concurrency, batch operations, and migrations.

What it does: This skill provides instructions and code patterns for working with Core Data in apps that have not adopted SwiftData. It covers NSPersistentContainer stack setup, context concurrency and Swift Concurrency integration, NSFetchedResultsController for list-driven UI, batch insert/delete/update requests, persistent history tracking, staged schema migrations, and composite attributes. It also includes testing guidance with in-memory stores, a common-mistakes table, and a review checklist.
When to use it: Use it when implementing or reviewing Core Data persistence, such as NSManagedObject subclasses, NSFetchedResultsController, bulk batch operations, persistent history tracking across targets, or staged schema migrations. It is intended for apps that have not adopted SwiftData; for Core Data and SwiftData coexistence or migration, a separate swiftdata skill is referenced.
Requirements: No scripts are shipped; it is instructions only. It assumes an Apple platform development environment with Core Data and Swift, and references optional companion reference files for persistent history and staged migration.

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.

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

swift

import CoreData
final class CoreDataStack: @unchecked Sendable {    static let shared = CoreDataStack()
    let container: NSPersistentContainer
    private init() {        container = NSPersistentContainer(name: "MyAppModel")        container.loadPersistentStores { _, error in            if let error { fatalError("Core Data store failed: \(error)") }        }        container.viewContext.automaticallyMergesChangesFromParent = true        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy    }
    var viewContext: NSManagedObjectContext { container.viewContext }
    func newBackgroundContext() -> NSManagedObjectContext {        container.newBackgroundContext()    }}

import CoreData
final class CoreDataStack: @unchecked Sendable {    static let shared = CoreDataStack()
    let container: NSPersistentContainer
    private init() {        container = NSPersistentContainer(name: "MyAppModel")        container.loadPersistentStores { _, error in            if let error { fatalError("Core Data store failed: \(error)") }        }        container.viewContext.automaticallyMergesChangesFromParent = true        container.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(_:) or performAndWait(_:) when accessing a context off its own queue.
Never pass NSManagedObject instances across context or thread boundaries. Pass NSManagedObjectID instead and re-fetch.
Set automaticallyMergesChangesFromParent = true on the viewContext.

swift

// 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 = newName        try context.save()    }}

// 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 = newName        try context.save()    }}

Swift Concurrency Integration

NSManagedObjectContext.perform(_:) has an async throws overload (iOS 15+). Avoid marking NSManagedObject subclasses as Sendable.

swift

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.id            item.title = record.title        }        try context.save()    }    // After save completes, viewContext auto-merges if configured}

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.id            item.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:

swift

let objectID = trip.objectID  // SendableTask.detached {    let bgContext = CoreDataStack.shared.newBackgroundContext()    try await bgContext.perform {        let trip = try bgContext.existingObject(with: objectID) as! CDTrip        trip.isFavorite = true        try bgContext.save()    }}

let objectID = trip.objectID  // SendableTask.detached {    let bgContext = CoreDataStack.shared.newBackgroundContext()    try await bgContext.perform {        let trip = try bgContext.existingObject(with: objectID) as! CDTrip        trip.isFavorite = true        try bgContext.save()    }}

NSFetchedResultsController

Efficiently drives UITableView / UICollectionView from a Core Data fetch request, with built-in change tracking and optional caching.

Docs: NSFetchedResultsController

swift

import CoreDataimport UIKit
class 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 = 20
        let controller = NSFetchedResultsController(            fetchRequest: request,            managedObjectContext: CoreDataStack.shared.viewContext,            sectionNameKeyPath: nil,            cacheName: "TripsCache"        )        controller.delegate = self        return controller    }()
    override func viewDidLoad() {        super.viewDidLoad()        try? fetchedResultsController.performFetch()    }
    // MARK: - UITableViewDataSource
    override 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.name        return 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)    }}

import CoreDataimport UIKit
class 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 = 20
        let controller = NSFetchedResultsController(            fetchRequest: request,            managedObjectContext: CoreDataStack.shared.viewContext,            sectionNameKeyPath: nil,            cacheName: "TripsCache"        )        controller.delegate = self        return controller    }()
    override func viewDidLoad() {        super.viewDidLoad()        try? fetchedResultsController.performFetch()    }
    // MARK: - UITableViewDataSource
    override 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.name        return 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(), call performFetch() 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

swift

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 = .objectIDs        let result = try context.execute(request) as? NSBatchInsertResult        if let ids = result?.result as? [NSManagedObjectID] {            NSManagedObjectContext.mergeChanges(                fromRemoteContextSave: [NSInsertedObjectsKey: ids],                into: [CoreDataStack.shared.viewContext]            )        }    }}

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 = .objectIDs        let result = try context.execute(request) as? NSBatchInsertResult        if let ids = result?.result as? [NSManagedObjectID] {            NSManagedObjectContext.mergeChanges(                fromRemoteContextSave: [NSInsertedObjectsKey: ids],                into: [CoreDataStack.shared.viewContext]            )        }    }}

NSBatchDeleteRequest (iOS 9+)

Docs: NSBatchDeleteRequest

swift

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 = .resultTypeObjectIDs        let result = try context.execute(request) as? NSBatchDeleteResult        if let ids = result?.result as? [NSManagedObjectID] {            NSManagedObjectContext.mergeChanges(                fromRemoteContextSave: [NSDeletedObjectsKey: ids],                into: [CoreDataStack.shared.viewContext]            )        }    }}

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 = .resultTypeObjectIDs        let result = try context.execute(request) as? NSBatchDeleteResult        if let ids = result?.result as? [NSManagedObjectID] {            NSManagedObjectContext.mergeChanges(                fromRemoteContextSave: [NSDeletedObjectsKey: ids],                into: [CoreDataStack.shared.viewContext]            )        }    }}

NSBatchUpdateRequest (iOS 8+)

swift

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 = .updatedObjectIDsResultType        let result = try context.execute(request) as? NSBatchUpdateResult        if let ids = result?.result as? [NSManagedObjectID] {            NSManagedObjectContext.mergeChanges(                fromRemoteContextSave: [NSUpdatedObjectsKey: ids],                into: [CoreDataStack.shared.viewContext]            )        }    }}

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 = .updatedObjectIDsResultType        let result = try context.execute(request) as? NSBatchUpdateResult        if 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.

For destructive or retryable batch work, use a proof loop: preflight the predicate and expected count, execute with an object-ID result type, merge IDs into live contexts, refetch, and assert the postcondition. On failure, restore a pristine fixture or prove the operation is idempotent before retrying; never blindly rerun a partially completed batch.

Persistent History Tracking

Track store-level changes across targets (app, extensions, widgets) and processes. The core workflow is:

Docs: NSPersistentHistoryChangeRequest

Enable persistent history and remote-change notifications before loading the store.
Observe changes and fetch transactions after the target's durable token.
Merge transaction notifications into live contexts, then persist the new token.
Purge only history that every relevant consumer has processed.

Load persistent-history.md [blocked] when implementing the store options, observer, token persistence, merge loop, or purge policy.

Staged Migration

NSStagedMigrationManager (iOS 17+) sequences schema migrations through ordered lightweight or custom stages. Stage inputs use compiled model-version checksums, not model names. Apps supporting systems below iOS 17 need the lightweight migration or mapping-model path.

Docs: NSStagedMigrationManager

Load staged-migration.md [blocked] when building the ordered stages, model references, custom handler, and persistent-store option.

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

swift

import CoreDataimport Testing
struct CoreDataTests {    func makeTestContainer() throws -> NSPersistentContainer {        let container = NSPersistentContainer(name: "MyAppModel")        let description = NSPersistentStoreDescription()        description.type = NSInMemoryStoreType        container.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.viewContext
        let trip = CDTrip(context: context)        trip.name = "Test Trip"        trip.startDate = .now        try context.save()
        let request: NSFetchRequest<CDTrip> = CDTrip.fetchRequest()        let trips = try context.fetch(request)        #expect(trips.count == 1)        #expect(trips.first?.name == "Test Trip")    }}

import CoreDataimport Testing
struct CoreDataTests {    func makeTestContainer() throws -> NSPersistentContainer {        let container = NSPersistentContainer(name: "MyAppModel")        let description = NSPersistentStoreDescription()        description.type = NSInMemoryStoreType        container.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.viewContext
        let trip = CDTrip(context: context)        trip.name = "Test Trip"        trip.startDate = .now        try 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 NSManagedObjectModel instance across tests to avoid "duplicate entity" warnings.
Use a single shared model loaded once:

swift

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}

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

References

Persistent history across targets and processes [blocked]
Staged lightweight and custom migration [blocked]
Apple docs: Core Data | NSPersistentContainer | NSFetchedResultsController | NSStagedMigrationManager

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/core-dataat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago

Core Data

Core Data

Contents

Stack Setup

Concurrency and Threading

Swift Concurrency Integration

NSFetchedResultsController

Batch Operations

NSBatchInsertRequest (iOS 13+)

NSBatchDeleteRequest (iOS 9+)

NSBatchUpdateRequest (iOS 8+)

Persistent History Tracking

Staged Migration

Composite Attributes

SwiftData Boundary

Testing

In-Memory Store for Tests

Common Mistakes

Review Checklist

References

Source and attribution

More from dpearson2699/swift-ios-skills

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices