1# Core Data and Swift Concurrency
2 
3Use this when:
4 
5- You need to use Core Data with async/await or actors.
6- `NSManagedObject` instances are crossing context or actor boundaries.
7- You are resolving default `@MainActor` isolation conflicts with generated NSManagedObject subclasses.
8 
9Skip this file if:
10 
11- The issue is general actor isolation, not Core Data specific. Use `actors.md`.
12- You need general Sendable guidance. Use `sendable.md`.
13 
14Jump to:
15 
16- Core Principles
17- Data Access Objects (DAO) Pattern
18- Working Without DAOs (NSManagedObjectID)
19- Bridging Closures to Async
20- Custom Actor Executor (Advanced)
21- Default MainActor Isolation
22- SwiftUI Integration
23- Common Mistakes
24 
25## Core Principles
26 
27### Thread safety still matters
28 
29Core Data's thread safety rules don't change with Swift Concurrency:
30- Can't pass `NSManagedObject` between threads
31- Must access objects on their context's thread
32- `NSManagedObjectID` is thread-safe (can pass around)
33 
34### NSManagedObject cannot be Sendable
35 
36```swift
37@objc(Article)
38public class Article: NSManagedObject {
39    @NSManaged public var title: String // ❌ Mutable, can't be Sendable
40}
41```
42 
43**Don't use `@unchecked Sendable`** - hides warnings without fixing safety.
44 
45> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.1: An introduction to Swift Concurrency and Core Data](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
46 
47## Available Async APIs
48 
49### Context perform
50 
51```swift
52extension NSManagedObjectContext {
53    func perform<T>(
54        schedule: ScheduledTaskType = .immediate,
55        _ block: @escaping () throws -> T
56    ) async rethrows -> T
57}
58```
59 
60### What's missing
61 
62No async alternative for:
63```swift
64func loadPersistentStores(
65    completionHandler: @escaping (NSPersistentStoreDescription, Error?) -> Void
66)
67```
68 
69Must bridge manually (see below).
70 
71## Data Access Objects (DAO)
72 
73Thread-safe value types representing managed objects.
74 
75### Pattern
76 
77```swift
78// Managed object (not Sendable)
79@objc(Article)
80public class Article: NSManagedObject {
81    @NSManaged public var title: String?
82    @NSManaged public var timestamp: Date?
83}
84 
85// DAO (Sendable)
86struct ArticleDAO: Sendable, Identifiable {
87    let id: NSManagedObjectID
88    let title: String
89    let timestamp: Date
90    
91    init?(managedObject: Article) {
92        guard let title = managedObject.title,
93              let timestamp = managedObject.timestamp else {
94            return nil
95        }
96        self.id = managedObject.objectID
97        self.title = title
98        self.timestamp = timestamp
99    }
100}
101```
102 
103### Benefits
104 
105- **Sendable**: Safe to pass across isolation domains
106- **Immutable**: No accidental mutations
107- **Clear API**: Explicit data transfer
108 
109### Drawbacks
110 
111- **Requires rewrite**: All fetch/mutation logic
112- **Boilerplate**: DAO for each entity
113- **Complexity**: Additional layer of abstraction
114 
115> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.2: Sendable and NSManageObjects](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
116 
117## Working Without DAOs
118 
119Pass only `NSManagedObjectID` between contexts.
120 
121### Basic pattern
122 
123```swift
124@MainActor
125func fetchArticle(id: NSManagedObjectID) -> Article? {
126    viewContext.object(with: id) as? Article
127}
128 
129func processInBackground(articleID: NSManagedObjectID) async throws {
130    let backgroundContext = container.newBackgroundContext()
131    try await backgroundContext.perform {
132        guard let article = backgroundContext.object(with: articleID) as? Article else {
133            return
134        }
135        // Process article
136        try backgroundContext.save()
137    }
138}
139```
140 
141### NSManagedObjectID is Sendable
142 
143```swift
144// Safe to pass between tasks
145let articleID = article.objectID
146 
147Task {
148    await processInBackground(articleID: articleID)
149}
150```
151 
152## Bridging Closures to Async
153 
154### Load persistent stores
155 
156```swift
157extension NSPersistentContainer {
158    func loadPersistentStores() async throws {
159        try await withCheckedThrowingContinuation { continuation in
160            self.loadPersistentStores { description, error in
161                if let error {
162                    continuation.resume(throwing: error)
163                } else {
164                    continuation.resume(returning: ())
165                }
166            }
167        }
168    }
169}
170 
171// Usage
172try await container.loadPersistentStores()
173```
174 
175## Simple CoreDataStore Pattern
176 
177Enforce isolation at API level:
178 
179```swift
180nonisolated struct CoreDataStore {
181    static let shared = CoreDataStore()
182    
183    let persistentContainer: NSPersistentContainer
184    private var viewContext: NSManagedObjectContext {
185        persistentContainer.viewContext
186    }
187    
188    private init() {
189        persistentContainer = NSPersistentContainer(name: "MyApp")
190        persistentContainer.viewContext.automaticallyMergesChangesFromParent = true
191        
192        Task { [persistentContainer] in
193            try? await persistentContainer.loadPersistentStores()
194        }
195    }
196    
197    // View context operations (main thread)
198    @MainActor
199    func perform(_ block: (NSManagedObjectContext) throws -> Void) rethrows {
200        try block(viewContext)
201    }
202    
203    // Background operations
204    @concurrent
205    func performInBackground<T>(
206        _ block: @escaping (NSManagedObjectContext) throws -> T
207    ) async rethrows -> T {
208        let context = persistentContainer.newBackgroundContext()
209        return try await context.perform {
210            try block(context)
211        }
212    }
213}
214```
215 
216### Usage
217 
218```swift
219// Main thread operations
220@MainActor
221func loadArticles() throws -> [Article] {
222    try CoreDataStore.shared.perform { context in
223        let request = Article.fetchRequest()
224        return try context.fetch(request)
225    }
226}
227 
228// Background operations
229func deleteAll() async throws {
230    try await CoreDataStore.shared.performInBackground { context in
231        let request = Article.fetchRequest()
232        let articles = try context.fetch(request)
233        articles.forEach { context.delete($0) }
234        try context.save()
235    }
236}
237```
238 
239### Why this pattern works
240 
241- **@MainActor**: Enforces view context on main thread
242- **@concurrent**: Forces background execution
243- **Compile-time safety**: Wrong isolation = error
244- **Simple**: No custom executors needed
245 
246## Custom Actor Executor (Advanced)
247 
248**Note**: Usually not needed. Consider simple pattern first.
249 
250> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.3: Using a custom Actor executor for Core Data (advanced)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
251 
252### Implementation
253 
254```swift
255final class NSManagedObjectContextExecutor: @unchecked Sendable, SerialExecutor {
256    private let context: NSManagedObjectContext
257    
258    init(context: NSManagedObjectContext) {
259        self.context = context
260    }
261    
262    func enqueue(_ job: consuming ExecutorJob) {
263        let unownedJob = UnownedJob(job)
264        let executor = asUnownedSerialExecutor()
265        
266        context.perform {
267            unownedJob.runSynchronously(on: executor)
268        }
269    }
270    
271    func asUnownedSerialExecutor() -> UnownedSerialExecutor {
272        UnownedSerialExecutor(ordinary: self)
273    }
274}
275```
276 
277### Actor usage
278 
279```swift
280actor CoreDataStore {
281    let persistentContainer: NSPersistentContainer
282    nonisolated let modelExecutor: NSManagedObjectContextExecutor
283    
284    nonisolated var unownedExecutor: UnownedSerialExecutor {
285        modelExecutor.asUnownedSerialExecutor()
286    }
287    
288    private init() {
289        persistentContainer = NSPersistentContainer(name: "MyApp")
290        let context = persistentContainer.newBackgroundContext()
291        modelExecutor = NSManagedObjectContextExecutor(context: context)
292    }
293    
294    func deleteAll<T: NSManagedObject>(
295        using request: NSFetchRequest<T>
296    ) throws {
297        let objects = try context.fetch(request)
298        objects.forEach { context.delete($0) }
299        try context.save()
300    }
301}
302```
303 
304### Drawbacks
305 
306- **Hidden complexity**: Executor details obscure Core Data
307- **Forces concurrency**: Even for main thread operations
308- **Not simpler**: More code than `perform { }`
309- **Error prone**: Easy to use wrong context
310 
311**Recommendation**: Use simple pattern instead.
312 
313## Default MainActor Isolation
314 
315### Problem with auto-generated code
316 
317When default isolation set to `@MainActor`, auto-generated managed objects conflict:
318 
319```swift
320// Auto-generated (can't modify)
321class Article: NSManagedObject {
322    // Inherits @MainActor, conflicts with NSManagedObject
323}
324```
325 
326**Error**: `Main actor-isolated initializer has different actor isolation from nonisolated overridden declaration`
327 
328### Solution: Manual code generation
329 
3301. Set entity to "Manual/None" code generation
3312. Generate class definitions
3323. Mark as `nonisolated`:
333 
334```swift
335nonisolated class Article: NSManagedObject {
336    @NSManaged public var title: String?
337    @NSManaged public var timestamp: Date?
338}
339 
340> **Course Deep Dive**: This topic is covered in detail in [Lesson 9.4: Autogenerated Core Data Objects and Default MainActor Isolation Conflicts](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
341```
342 
343**Benefit**: Full control over isolation.
344 
345## Common Patterns
346 
347### Fetch on main thread
348 
349```swift
350@MainActor
351func fetchArticles() throws -> [Article] {
352    let request = Article.fetchRequest()
353    return try viewContext.fetch(request)
354}
355```
356 
357### Background save
358 
359```swift
360func saveInBackground() async throws {
361    let context = container.newBackgroundContext()
362    try await context.perform {
363        let article = Article(context: context)
364        article.title = "New Article"
365        try context.save()
366    }
367}
368```
369 
370### Pass ID, fetch in context
371 
372```swift
373@MainActor
374func displayArticle(id: NSManagedObjectID) {
375    guard let article = viewContext.object(with: id) as? Article else {
376        return
377    }
378    // Use article
379}
380 
381func processArticle(id: NSManagedObjectID) async throws {
382    try await CoreDataStore.shared.performInBackground { context in
383        guard let article = context.object(with: id) as? Article else {
384            return
385        }
386        // Process article
387        try context.save()
388    }
389}
390```
391 
392### Batch operations
393 
394```swift
395@concurrent
396func deleteAllArticles() async throws {
397    try await CoreDataStore.shared.performInBackground { context in
398        let request = NSFetchRequest<NSFetchRequestResult>(entityName: "Article")
399        let deleteRequest = NSBatchDeleteRequest(fetchRequest: request)
400        try context.execute(deleteRequest)
401    }
402}
403```
404 
405## SwiftUI Integration
406 
407### Environment injection
408 
409```swift
410@main
411struct MyApp: App {
412    let persistentContainer = NSPersistentContainer(name: "MyApp")
413    
414    var body: some Scene {
415        WindowGroup {
416            ContentView()
417                .environment(\.managedObjectContext, persistentContainer.viewContext)
418        }
419    }
420}
421```
422 
423### View usage
424 
425```swift
426struct ContentView: View {
427    @Environment(\.managedObjectContext) private var viewContext
428    @FetchRequest(
429        sortDescriptors: [NSSortDescriptor(keyPath: \Article.timestamp, ascending: true)]
430    ) private var articles: FetchedResults<Article>
431    
432    var body: some View {
433        List(articles) { article in
434            Text(article.title ?? "")
435        }
436    }
437}
438```
439 
440## Best Practices
441 
4421. **Pass NSManagedObjectID only** - never managed objects
4432. **Use perform { }** - don't access context directly
4443. **@MainActor for view context** - enforce main thread
4454. **@concurrent for background** - force background execution
4465. **Manual code generation** - control isolation
4476. **Keep it simple** - avoid custom executors unless needed
4487. **Enable Core Data debugging** - catch thread violations
4498. **Merge changes automatically** - `automaticallyMergesChangesFromParent = true`
4509. **Use background contexts** - for heavy operations
45110. **Test with Thread Sanitizer** - catch violations early
452 
453## Debugging
454 
455### Enable Core Data concurrency debugging
456 
457```swift
458// Launch argument
459-com.apple.CoreData.ConcurrencyDebug 1
460```
461 
462Crashes immediately on thread violations.
463 
464### Thread Sanitizer
465 
466Enable in scheme settings to catch data races.
467 
468### Assertions
469 
470```swift
471@MainActor
472func fetchArticles() -> [Article] {
473    assert(Thread.isMainThread)
474    // Fetch from viewContext
475}
476```
477 
478## Decision Tree
479 
480```
481Need to access Core Data?
482├─ UI/View context?
483│  └─ Use @MainActor + viewContext
484│
485├─ Background operation?
486│  ├─ Quick operation? → perform { } on background context
487│  └─ Batch operation? → NSBatchDeleteRequest/NSBatchUpdateRequest
488│
489├─ Pass between contexts?
490│  └─ Use NSManagedObjectID only
491│
492└─ Need Sendable type?
493   ├─ Can refactor? → Use DAO pattern
494   └─ Can't refactor? → Pass NSManagedObjectID
495```
496 
497## Migration Strategy
498 
499### For existing projects
500 
5011. **Enable manual code generation** for all entities
5022. **Mark entities as nonisolated** if using default @MainActor
5033. **Wrap Core Data access** in CoreDataStore
5044. **Use @MainActor** for view context operations
5055. **Use @concurrent** for background operations
5066. **Pass NSManagedObjectID** between contexts
5077. **Test with debugging enabled**
508 
509### For new projects
510 
5111. **Start with simple pattern** (CoreDataStore)
5122. **Manual code generation** from the start
5133. **Consider DAOs** if heavy cross-context usage
5144. **Enable strict concurrency** early
515 
516## Common Mistakes
517 
518### ❌ Passing managed objects
519 
520```swift
521func process(article: Article) async {
522    // ❌ Article not Sendable
523}
524```
525 
526### ❌ Accessing context from wrong thread
527 
528```swift
529func background() async {
530    let articles = viewContext.fetch(request) // ❌ Not on main thread
531}
532```
533 
534### ❌ Using @unchecked Sendable
535 
536```swift
537extension Article: @unchecked Sendable {} // ❌ Doesn't make it safe
538```
539 
540### ❌ Not using perform
541 
542```swift
543func save() async {
544    backgroundContext.save() // ❌ Not on context's thread
545}
546```
547 
548## Common Mistakes Agents Make
549 
550- **Passing `NSManagedObject` instances across actors**: Always transfer `NSManagedObjectID` or a Sendable value snapshot instead.
551- **Using `@unchecked Sendable` on `NSManagedObject`**: This does not make it thread-safe. The object is still bound to its context's queue.
552- **Skipping `perform { }`**: All background context access must go through `perform` or `performAndWait`.
553- **Accessing `viewContext` from a background task**: The view context belongs to the main actor; access it only from `@MainActor`-isolated code.
554 
555## Further Learning
556 
557For Core Data best practices, migration strategies, and advanced patterns:
558- [Core Data Best Practices](https://github.com/avanderlee/CoreDataBestPractices)
559- [Swift Concurrency Course](https://www.swiftconcurrencycourse.com)
560 
561