Agent Skills: SwiftData & CoreData Persistence

SwiftData & CoreData Persistence

Overview

SwiftData and CoreData are NOT interchangeable. Each has specific strengths, migration traps, and performance patterns. Wrong framework choice or migration strategy causes production crashes.

Core principle: Choose framework based on app constraints, version models from day one, never store BLOBs in the database.

Framework Selection

digraph framework_choice {
    "New iOS app?" [shape=diamond];
    "iOS 17+ only?" [shape=diamond];
    "Simple data model?" [shape=diamond];
    "iCloud sync?" [shape=diamond];
    "Existing CoreData?" [shape=diamond];
    "Use SwiftData" [shape=box, style=filled, fillcolor=lightgreen];
    "Use CoreData" [shape=box, style=filled, fillcolor=lightblue];
    "Stay with CoreData" [shape=box, style=filled, fillcolor=lightblue];

    "New iOS app?" -> "iOS 17+ only?" [label="yes"];
    "New iOS app?" -> "Existing CoreData?" [label="no"];
    "Existing CoreData?" -> "Stay with CoreData" [label="yes"];
    "Existing CoreData?" -> "iOS 17+ only?" [label="no"];
    "iOS 17+ only?" -> "Simple data model?" [label="yes"];
    "iOS 17+ only?" -> "Use CoreData" [label="no"];
    "Simple data model?" -> "iCloud sync?" [label="yes"];
    "Simple data model?" -> "Use CoreData" [label="no"];
    "iCloud sync?" -> "Use SwiftData" [label="yes"];
    "iCloud sync?" -> "Use SwiftData" [label="no"];
}

Choose SwiftData When

• New app, iOS 17+ deployment target
• Simple relationships (mostly 1:1 or 1:N, few complex queries)
• SwiftUI-first architecture
• iCloud sync needed with minimal configuration

Choose CoreData When

• iOS 16 or earlier support required
• Complex queries with NSCompoundPredicate, subqueries
• UIKit-heavy app with NSFetchedResultsController
• Existing CoreData codebase (migration complex, stay with CoreData)
• Performance critical (as of 2025, CoreData still faster)
• Abstract entities or inheritance hierarchies

Migration Death Traps

Trap 1: Unversioned → Versioned with iCloud

CRITICAL: If you shipped unversioned SwiftData with iCloud sync, users will crash on first migration.

Error: "Cannot use staged migration with an unknown model version"

Why: CloudKit requires versioned schemas for sync consistency.

Solution:

// ❌ WRONG: Adding versioning after shipping unversioned + iCloud
// This will crash for all existing users

// ✅ CORRECT: Two-phase migration
// Version 1.1: Add versioning WITHOUT schema changes
enum SchemaV1: VersionedSchema {
    static var models: [any PersistentModel.Type] { [User.self] }

    @Model
    final class User {
        var name: String
        var email: String
        // EXACT same schema as shipped v1.0
    }
}

// Version 1.2: Now safe to add new properties
enum SchemaV2: VersionedSchema {
    static var models: [any PersistentModel.Type] { [User.self] }

    @Model
    final class User {
        var name: String
        var email: String
        var createdAt: Date? // New property
    }
}

Rule: Start with versioned schemas from day one, or ship versioning wrapper first.

Trap 2: Unique Constraint with Duplicates

Scenario: Adding @Attribute(.unique) when data has duplicates.

Result: Lightweight migration fails, app becomes non-functional.

Solution: Complex migration with deduplication BEFORE applying constraint.

struct DeduplicateThenUnique: MigrationStage {
    func migrate(context: ModelContext) throws {
        let items = try context.fetch(FetchDescriptor<OldSchema.Product>())
        let grouped = Dictionary(grouping: items, by: { $0.sku })

        // Keep first, delete duplicates
        for (_, duplicates) in grouped where duplicates.count > 1 {
            for item in duplicates.dropFirst() {
                context.delete(item)
            }
        }
        try context.save()
    }
}

Rule: Clean data BEFORE applying constraints. Test with production data backup.

Trap 3: iCloud Sync Blocks Migrations

CRITICAL: Once iCloud sync enabled, SwiftData blocks migrations that break lightweight compatibility.

What this means:

• Cannot rename properties (breaks sync)
• Cannot change relationship delete rules (breaks sync)
• Cannot remove required properties (breaks sync)

Workaround:

// Instead of renaming (blocked):
// @Model class User {
//     var userName: String // Renamed from 'name'
// }

// Add new, deprecate old (allowed):
@Model class User {
    var name: String // Keep for backward compatibility
    var userName: String? // New preferred field

    var displayName: String {
        userName ?? name // Compute from both
    }
}

Rule: With iCloud, only additive changes allowed. Design schema carefully upfront.

Trap 4: Main Thread Migration Blocking

Symptom: White screen for 3-5 seconds on app launch after update.

Cause: Large dataset migration runs on main thread.

Solution: Background initialization.

// ✅ Initialize container on background thread
Task.detached {
    let container = try await ModelContainer(
        for: User.self,
        migrationPlan: MigrationPlan.self
    )
    await MainActor.run {
        self.container = container
    }
}

Rule: Always test migrations with realistic data size (1000+ records).

Performance Patterns

Pattern 1: Batch Fetching

Problem: Loading 1000+ objects at once consumes memory, blocks UI.

Solution: fetchBatchSize for lazy loading.

// ❌ WRONG: Loads all 1000 posts into memory
let request: NSFetchRequest<Post> = Post.fetchRequest()
let posts = try context.fetch(request)

// ✅ CORRECT: Loads 20 at a time as needed
let request: NSFetchRequest<Post> = Post.fetchRequest()
request.fetchBatchSize = 20
let posts = try context.fetch(request)

Rule: Always set fetchBatchSize for feeds, lists, paginated views.

Pattern 2: BLOB Storage

Problem: Storing images/videos in CoreData/SwiftData kills performance.

Rule:

• < 100KB: Store inline (safe)
• 100KB - 1MB: Separate entity with relationship
• > 1MB: File system + store path in database

// ❌ WRONG: 2MB images in Post entity
@Model
class Post {
    var title: String
    @Attribute(.externalStorage) var image: Data // Still loads eagerly!
}

// ✅ CORRECT: File system storage
@Model
class Post {
    var title: String
    var imagePath: String? // "images/post-123.jpg"
}

// Load image on-demand
func loadImage(for post: Post) -> UIImage? {
    guard let path = post.imagePath else { return nil }
    let url = FileManager.documentsDirectory.appendingPathComponent(path)
    return UIImage(contentsOfFile: url.path)
}

Why: Database fetches load full objects. BLOBs inflate memory usage even when not displayed.

Pattern 3: Faulting for Relationships

Problem: Fetching posts eagerly loads all related users and images.

Solution: Return faults, load on access.

// ✅ Relationships default to faults (good)
let request: NSFetchRequest<Post> = Post.fetchRequest()
request.relationshipKeyPathsForPrefetching = [] // Don't prefetch
let posts = try context.fetch(request)

// Access triggers individual fault:
let authorName = posts[0].author.name // Only now loads User

// ✅ Prefetch when you know you'll need it:
request.relationshipKeyPathsForPrefetching = ["author"]

Rule: Only prefetch relationships you'll access for ALL fetched objects.

Pattern 4: NSFetchedResultsController (CoreData)

For: Table/collection views with live updates.

Why: Lazy loads, automatic UI updates, sectioning built-in.

let request: NSFetchRequest<Post> = Post.fetchRequest()
request.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]
request.fetchBatchSize = 20

let frc = NSFetchedResultsController(
    fetchRequest: request,
    managedObjectContext: context,
    sectionNameKeyPath: nil,
    cacheName: "PostsCache"
)

frc.delegate = self
try frc.performFetch()

// UITableView uses frc.fetchedObjects

Rule: Use FRC for all CoreData-backed table/collection views.

SwiftData Limitations (as of iOS 18)

| Feature | CoreData | SwiftData | Workaround | |---------|----------|-----------|------------| | NSCompoundPredicate | ✅ | ❌ | Multiple queries | | NSFetchedResultsController | ✅ | ❌ | @Query in SwiftUI | | Abstract entities | ✅ | ❌ | Use protocols | | Child contexts | ✅ | ❌ | Use ModelContext | | Subclassing models | ✅ | ❌ | Don't subclass | | Performance | Faster | Slower | Wait for updates |

Common Mistakes

| Mistake | Reality | Fix | |---------|---------|-----| | "Migrations are automatic" | Only lightweight migrations. Unique constraints, renames require complex migrations. | Test with production data | | "I'll version later" | Unversioned + iCloud = crash on first migration | Version from day one | | "SwiftData = CoreData simplified" | SwiftData has different rules (no subclassing, different delete rules) | Learn SwiftData-specific constraints | | "externalStorage attribute fixes BLOBs" | Still loaded into memory on fetch | Store in file system | | "I can rename properties freely" | With iCloud, renames blocked | Add new property, keep old | | "Migration won't block UI" | Large datasets block main thread | Background initialization |

Migration Checklist

Before shipping schema change:

• [ ] Defined versioned schemas (V1, V2)
• [ ] Written migration stage if complex (deduplication, renames)
• [ ] Tested with production data backup (1000+ records)
• [ ] Tested migration on background thread (no white screen)
• [ ] Verified iCloud sync works post-migration
• [ ] Checked new properties have defaults or are optional
• [ ] Confirmed unique constraints applied to clean data only

Quick Reference

SwiftData:

// Basic model
@Model
class User {
    @Attribute(.unique) var email: String
    var name: String
    @Relationship(deleteRule: .cascade) var posts: [Post]
}

// Versioned schemas
enum SchemaV1: VersionedSchema {
    static var models: [any PersistentModel.Type] { [User.self] }
    @Model final class User { /* ... */ }
}

// Query (SwiftUI)
@Query(sort: \.createdAt, order: .reverse) var users: [User]

CoreData:

// Fetch with batching
let request: NSFetchRequest<User> = User.fetchRequest()
request.fetchBatchSize = 20
request.predicate = NSPredicate(format: "name CONTAINS[cd] %@", searchText)

// Background context
let bgContext = container.newBackgroundContext()
bgContext.perform {
    // Heavy work here
    try? bgContext.save()
}

Red Flags - STOP and Reconsider

• Shipped unversioned schema with iCloud → Ship versioning wrapper first
• Adding unique constraint to dirty data → Run deduplication migration
• Storing multi-MB files in database → Move to file system
• White screen on launch after update → Background migration
• Fetch taking >500ms → Add fetchBatchSize, check for BLOBs
• "I'll handle migration when users complain" → Test NOW with production data

Real-World Impact

Before: App crashes for 100% of users with iCloud enabled after first migration (unversioned→versioned trap).

After: Ship v1.1 with versioning wrapper (no schema change), then v1.2 with actual changes. Zero crashes.

Before: Feed loads in 4 seconds with 1000 posts + 2MB images each.

After: Images moved to file system, fetchBatchSize = 20. Feed loads in 300ms, lazy-loads images.