curiositech/ios-core-data-architect

iOS Core Data Architect

Expert in Core Data persistence, CloudKit synchronization, schema migrations, and migration paths to SwiftData.

Activation Triggers

Activate on: "Core Data", "NSManagedObject", "CloudKit sync", "Core Data migration", "NSFetchedResultsController", "NSPersistentContainer", "SwiftData migration", "lightweight migration", "Core Data performance"

NOT for: SwiftUI state management → swiftui-data-flow-expert | Server databases → data-pipeline-engineer | SQLite direct → mobile-offline-sync-architect

Quick Start

1. Assess project state — new project? Use SwiftData. Existing Core Data? Evaluate migration vs coexistence.
2. Design data model — entities, relationships, fetch indexes in the .xcdatamodeld editor
3. Configure persistent container — NSPersistentCloudKitContainer for CloudKit sync, NSPersistentContainer for local-only
4. Implement migration plan — lightweight (automatic) or heavyweight (mapping model) depending on schema changes
5. Optimize fetching — batch size, prefetching, background contexts for heavy operations

Core Capabilities

| Domain | Technologies | |--------|-------------| | Persistence | NSPersistentContainer, NSManagedObjectContext, WAL mode | | CloudKit | NSPersistentCloudKitContainer, CKRecord zone, conflict resolution | | Migrations | Lightweight migration, mapping models, progressive migration | | Performance | NSBatchInsertRequest, NSBatchDeleteRequest, faulting, prefetch | | SwiftData | Coexistence with Core Data, migration path, @Model from NSManagedObject |

Architecture Patterns

Core Data Stack Setup with CloudKit

class PersistenceController {
    static let shared = PersistenceController()

    let container: NSPersistentCloudKitContainer

    init(inMemory: Bool = false) {
        container = NSPersistentCloudKitContainer(name: "MyApp")

        guard let description = container.persistentStoreDescriptions.first else {
            fatalError("No store description")
        }

        if inMemory {
            description.url = URL(fileURLWithPath: "/dev/null")
        }

        // CloudKit configuration
        description.cloudKitContainerOptions = NSPersistentCloudKitContainerOptions(
            containerIdentifier: "iCloud.com.example.myapp"
        )

        // Enable remote change notifications
        description.setOption(true as NSNumber,
            forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)

        // Enable persistent history tracking
        description.setOption(true as NSNumber,
            forKey: NSPersistentHistoryTrackingKey)

        container.loadPersistentStores { _, error in
            if let error { fatalError("Store failed: \(error)") }
        }

        container.viewContext.automaticallyMergesChangesFromParent = true
        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
    }

    // Background context for heavy operations
    func newBackgroundContext() -> NSManagedObjectContext {
        let context = container.newBackgroundContext()
        context.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
        return context
    }
}

Progressive Migration Strategy

Version 1 → Version 2 (add optional column):
  └─ Lightweight migration (automatic)

Version 2 → Version 3 (rename attribute):
  └─ Mapping model required (heavyweight)

Version 3 → Version 4 (split entity):
  └─ Custom migration with NSEntityMigrationPolicy

Strategy: Progressive migration chain
  v1 → v2 → v3 → v4 (each step is a known migration)
  NOT: v1 → v4 directly (complex, error-prone)

Code:
  for migration in migrationChain {
    try coordinator.addPersistentStore(
      ofType: NSSQLiteStoreType,
      configurationName: nil,
      at: storeURL,
      options: [NSMigratePersistentStoresAutomaticallyOption: true,
                NSInferMappingModelAutomaticallyOption: migration.isLightweight]
    )
  }

SwiftData Coexistence (Migration Path)

// Phase 1: Core Data and SwiftData side-by-side
// Share the same SQLite store file
let schema = Schema([NewEntity.self])   // SwiftData models
let config = ModelConfiguration(
    url: existingCoreDataStoreURL       // Same store as Core Data
)
let container = try ModelContainer(for: schema, configurations: [config])

// Phase 2: Gradually move entities from Core Data to SwiftData
// - New entities: @Model (SwiftData)
// - Existing entities: NSManagedObject (Core Data)
// - Read from both, write to SwiftData for new data

// Phase 3: Full migration
// - Convert all NSManagedObject subclasses to @Model
// - Remove .xcdatamodeld file
// - Use ModelContainer exclusively

Anti-Patterns

1. Using viewContext for writes — viewContext is on the main thread; heavy writes block the UI. Use performBackgroundTask or newBackgroundContext() for inserts and batch operations.
2. No batch operations for bulk data — inserting 10K records one-by-one creates 10K change notifications. Use NSBatchInsertRequest which bypasses the context and writes directly.
3. Ignoring faulting — accessing all properties of all objects in a list. Core Data uses faulting to lazy-load; respect it by only accessing displayed properties. Set fetchBatchSize.
4. Heavyweight migration without testing — mapping models are complex and fail silently with data corruption. Test every migration path against real production data copies.
5. Skipping persistent history tracking — required for CloudKit sync and multi-process coordination (widgets, extensions). Always enable NSPersistentHistoryTrackingKey.

Quality Checklist

[ ] Persistent container configured correctly (CloudKit or local)
[ ] viewContext used only for reads; background context for writes
[ ] NSBatchInsertRequest used for bulk operations
[ ] Fetch requests have fetchBatchSize set (typically 20-50)
[ ] Migration plan documented for each model version
[ ] Lightweight migration tested between all adjacent versions
[ ] CloudKit sync tested (if applicable) with conflict resolution
[ ] Persistent history tracking enabled
[ ] NSFetchedResultsController used for table/list data sources
[ ] Background context mergePolicy set explicitly
[ ] Unit tests use in-memory store for speed
[ ] SwiftData migration path documented for future transition