Core Data Agent Skill

Creating multiple NSManagedObjectModel instances can lead to the error: Failed to find a unique match for an NSEntityDescription.

To prevent this, implement a shared model instance via an extension on NSManagedObjectModel. This ensures all test containers use the exact same model definition.

extension NSManagedObjectModel {
    static let shared: NSManagedObjectModel = {
        guard let modelURL = Bundle.main.url(forResource: "Model", withExtension: "momd"),
              let model = NSManagedObjectModel(contentsOf: modelURL) else {
            fatalError("Failed to load model")
        }
        return model
    }()
}

// Use in tests
container = NSPersistentContainer(name: "Model", managedObjectModel: .shared)

Core Data uses 'faulting' to keep memory usage low, but accessing properties on a fault can trigger individual database hits (the N+1 problem). Use these strategies to optimize performance:

Prefetching Relationships

Use relationshipKeyPathsForPrefetching to fetch related objects in a single batch. This is highly recommended when you know you will access relationships in a loop.

Returning Objects without Faults

Set returnsObjectsAsFaults = false if you know you will access all properties of the fetched objects immediately. This is useful for small result sets but should be avoided for very large datasets to prevent high memory usage.

// Prefetching
let fetchRequest = Article.fetchRequest()
fetchRequest.relationshipKeyPathsForPrefetching = ["category", "attachments"]

// Disabling faults
fetchRequest.returnsObjectsAsFaults = false

A complete persistent history implementation typically consists of four functional components:

1. Observer: Listens for .NSPersistentStoreRemoteChange notifications from the NSPersistentStoreCoordinator.
2. Fetcher: Uses NSPersistentHistoryChangeRequest to retrieve transactions from the log, often using an NSPersistentHistoryToken to fetch only changes occurring after the last processed transaction.
3. Merger: Takes the fetched transactions and applies them to the active NSManagedObjectContext (usually the viewContext) using NSManagedObjectContext.mergeChanges(fromRemoteContextSave:into:).
4. Cleaner: Periodically executes NSPersistentHistoryChangeRequest.deleteHistory(before:) to remove old transactions and prevent the log from growing indefinitely.

Core Data supports different concurrency models for saving:

• View Context: Used for the main thread; typically used for UI-related data.
• Background Context: Created via container.newBackgroundContext(). Use context.perform { ... } to ensure thread safety when making changes and saving.
• Nested Contexts: A child context can have a parent context. Saving a child context pushes changes to the parent but does not persist them to disk. You must save the parent context to commit changes to the persistent store.

// Nested Context Example
let parentContext = container.viewContext
let childContext = NSManagedObjectContext(concurrencyType: .mainQueueConcurrencyType)
childContext.parent = parentContext

// 1. Save child to push changes to parent
try? childContext.save()

// 2. Save parent to persist to disk
try? parentContext.save()

Core Data uses different context types to manage threading and data flow:

• View Context: The main queue context. Use this exclusively for UI operations and anything running on the main thread.
• Background Context: A private queue context. Use this for heavy processing, data imports, or complex calculations to avoid blocking the UI. It runs on a background thread.
• Child Context: A context that has a parent context. When a child context saves, it pushes its changes to the parent context rather than directly to the persistent store.

When using Core Data with Swift Concurrency, the fundamental thread safety rules remain unchanged:

• Do not pass NSManagedObject between threads/tasks. Managed objects are not Sendable because they are mutable and tied to a specific context.
• Access objects on their context's thread. Always ensure you are interacting with an object within the isolation domain of its parent NSManagedObjectContext.
• Use NSManagedObjectID for cross-thread communication. NSManagedObjectID is thread-safe and can be passed between tasks or contexts to re-fetch the object in the target context.

Warning: Avoid using @unchecked Sendable to bypass compiler warnings; this hides safety issues without actually fixing the underlying thread-safety violations.

Lightweight migration automatically handles the following changes:

Attributes:

• Add or remove an attribute.
• Change an attribute from optional to non-optional (requires a default value).
• Change an attribute from non-optional to optional.
• Rename an attribute (requires a Renaming Identifier).

Relationships:

• Add or remove a relationship.
• Rename a relationship (requires a Renaming Identifier).
• Change cardinality (e.g., to-one to to-many).
• Change ordering (ordered vs non-ordered).

Entities:

• Add or remove an entity.
• Rename an entity (requires a Renaming Identifier).
• Create parent/child entity relationships.
• Move attributes or entities within the hierarchy.

Limitations:

• You cannot merge entity hierarchies (entities without a common parent cannot be merged into a shared parent via lightweight migration).