iOS Data Persistence Skill

Storage Selection Guide

Decision Flowchart

Is the data sensitive (tokens, passwords, keys)?
  YES → Keychain (NEVER UserDefaults)
  NO ↓

Is it a simple user preference (theme, flag, small string)?
  YES → Need sync across devices?
    YES → NSUbiquitousKeyValueStore
    NO  → @AppStorage / UserDefaults
  NO ↓

Is it a large binary file (image, video, PDF)?
  YES → FileManager (store path/URL reference in DB if needed)
  NO ↓

Is it structured/relational data?
  YES → iOS 17+ minimum?
    YES → SwiftData
    NO  → Core Data
  NO ↓

Need full SQL control or cross-platform DB?
  YES → SQLite via GRDB.swift
  NO  → Codable + FileManager (JSON/plist file)

Core Rules

General

• Use SwiftData for new iOS 17+ projects -- simpler API than Core Data
• Use Keychain for ALL sensitive data (tokens, passwords, API keys) -- NEVER UserDefaults
• Use @AppStorage only for simple preferences -- not large data or collections
• Store large blobs (images, video) on disk via FileManager, keep only the path/URL in DB
• Always handle persistence errors -- do not force-try in production

SwiftData Rules

• Always use isStoredInMemoryOnly: true for test ModelContainers
• Use @ModelActor for background SwiftData operations -- Model objects are NOT Sendable
• Pass PersistentIdentifier (Sendable) between actors, not model objects
• Use FetchDescriptor.fetchLimit for pagination -- never fetch all records unbounded
• CloudKit models: all properties must have defaults or be optional, no .unique
• Add #Index (iOS 18+) on frequently queried properties for performance
• Prefer @Transient for computed/cached properties that should not be persisted

Core Data Rules

• Batch operations (NSBatchInsertRequest, etc.) bypass validation -- use for bulk imports (10x faster)
• Always merge batch operation results into viewContext via NSManagedObjectContext.mergeChanges
• Use fetchBatchSize (default 0 = fetch all) -- set to ~20 for table/collection views
• Use newBackgroundContext() or performBackgroundTask for writes -- never block main thread
• Set automaticallyMergesChangesFromParent = true on viewContext for auto UI refresh

Storage Rules

• UserDefaults synchronize is unnecessary since iOS 12 -- system handles it
• FileManager: use .applicationSupportDirectory for internal data, .documentDirectory for user-visible files
• tmp/ and Library/Caches/ can be purged by system -- do not store critical data there
• iCloud KVS: 1MB total limit, 1024 keys max, values up to 1MB each
• GRDB: use ValueObservation for reactive SwiftUI integration

SwiftData Quick Reference

Define a Model

import SwiftData

@Model
final class Task {
    var title: String
    var isCompleted: Bool = false
    var createdAt: Date = Date.now
    @Attribute(.externalStorage) var imageData: Data?
    @Relationship(deleteRule: .cascade, inverse: \Tag.tasks)
    var tags: [Tag] = []

    init(title: String) {
        self.title = title
    }
}

@Model
final class Tag {
    @Attribute(.unique) var name: String
    var tasks: [Task] = []

    init(name: String) {
        self.name = name
    }
}

Setup Container

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup { ContentView() }
            .modelContainer(for: [Task.self, Tag.self])
    }
}

Query and Mutate

struct TaskListView: View {
    @Query(sort: \Task.createdAt, order: .reverse)
    private var tasks: [Task]
    @Environment(\.modelContext) private var context

    var body: some View {
        List(tasks) { task in
            Text(task.title)
        }
    }

    func addTask(title: String) {
        let task = Task(title: title)
        context.insert(task)
        // autosave handles the rest
    }

    func deleteTask(_ task: Task) {
        context.delete(task)
    }
}

Predicate

let incomplete = #Predicate<Task> { !$0.isCompleted }
let search = #Predicate<Task> { task in
    task.title.localizedStandardContains("meeting")
}

See references/swiftdata.md for full details.

Core Data Quick Reference

Setup

let container = NSPersistentContainer(name: "Model")
container.loadPersistentStores { _, error in
    if let error { fatalError("Store failed: \(error)") }
}
container.viewContext.automaticallyMergesChangesFromParent = true

Fetch

let request = NSFetchRequest<Task>(entityName: "Task")
request.predicate = NSPredicate(format: "isCompleted == %@", NSNumber(value: false))
request.sortDescriptors = [NSSortDescriptor(keyPath: \Task.createdAt, ascending: false)]
request.fetchBatchSize = 20
let tasks = try context.fetch(request)

Batch Insert (Bulk Performance)

let request = NSBatchInsertRequest(entity: Task.entity(), objects: dictionaries)
request.resultType = .objectIDs
let result = try context.execute(request) as! NSBatchInsertResult
let changes = [NSInsertedObjectIDsKey: result.objectIDs!]
NSManagedObjectContext.mergeChanges(fromRemoteContextSave: changes, into: [viewContext])

See references/coredata.md for full details.

Other Storage Quick Reference

@AppStorage

struct SettingsView: View {
    @AppStorage("isDarkMode") private var isDarkMode = false
    @AppStorage("username") private var username = ""

    var body: some View {
        Toggle("Dark Mode", isOn: $isDarkMode)
    }
}

Keychain (via wrapper)

func saveToKeychain(account: String, data: Data) throws {
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrAccount as String: account,
        kSecValueData as String: data
    ]
    SecItemDelete(query as CFDictionary)
    let status = SecItemAdd(query as CFDictionary, nil)
    guard status == errSecSuccess else {
        throw KeychainError.saveFailed(status)
    }
}

FileManager -- Save Codable

func save<T: Encodable>(_ object: T, to filename: String) throws {
    let url = FileManager.default
        .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
        .appendingPathComponent(filename)
    try FileManager.default.createDirectory(
        at: url.deletingLastPathComponent(),
        withIntermediateDirectories: true
    )
    let data = try JSONEncoder().encode(object)
    try data.write(to: url, options: .atomic)
}

See references/storage.md for full details.

Common Patterns

Repository Pattern (SwiftData)

@ModelActor
actor TaskRepository {
    func create(title: String) throws -> PersistentIdentifier {
        let task = Task(title: title)
        modelContext.insert(task)
        try modelContext.save()
        return task.persistentModelID
    }

    func fetchIncomplete() throws -> [PersistentIdentifier] {
        let descriptor = FetchDescriptor<Task>(
            predicate: #Predicate { !$0.isCompleted },
            sortBy: [SortDescriptor(\.createdAt, order: .reverse)]
        )
        return try modelContext.fetch(descriptor).map(\.persistentModelID)
    }

    func complete(id: PersistentIdentifier) throws {
        guard let task = modelContext.model(for: id) as? Task else { return }
        task.isCompleted = true
        try modelContext.save()
    }
}

Offline-First Architecture

// 1. Define local SwiftData model as source of truth
// 2. Sync layer: fetch from API → upsert into SwiftData
// 3. UI reads only from SwiftData via @Query
// 4. Writes go to SwiftData first, then queue API calls
// 5. Use ModelContext.enumerate for large dataset processing

Test Container

@MainActor
func makeTestContainer() throws -> ModelContainer {
    let config = ModelConfiguration(isStoredInMemoryOnly: true)
    let container = try ModelContainer(
        for: Task.self, Tag.self,
        configurations: config
    )
    return container
}

Performance Checklist

• [ ] Use fetchLimit on all list queries -- never fetch unbounded
• [ ] Add #Index (iOS 18) or Core Data indexes on frequently filtered/sorted properties
• [ ] Use @Attribute(.externalStorage) for Data properties > a few KB
• [ ] Use @ModelActor / background context for writes > 100 objects
• [ ] Use enumerate() instead of fetch() for processing large datasets (controls memory)
• [ ] Set fetchBatchSize = 20 on Core Data fetch requests for lists
• [ ] Use batch operations for bulk imports (Core Data)
• [ ] Profile with Instruments > Core Data template to find slow fetches

Migration Checklist

SwiftData

1. Create a new VersionedSchema conforming type for each schema version
2. Define SchemaMigrationPlan with ordered list of schemas
3. Use .lightweight stage when only adding/renaming properties
4. Use .custom stage when transforming data between versions
5. Pass migration plan to ModelContainer configuration

Core Data

1. Lightweight: adding optional attributes, adding entities -- automatic, no code needed
2. Heavyweight: create mapping model (.xcmappingmodel) for complex changes
3. Always test migration with production-size dataset before release

File References

• SwiftData Deep Dive -- @Model, @Query, #Predicate, migrations, CloudKit, concurrency
• Core Data Deep Dive -- NSPersistentContainer, fetching, batch ops, CloudKit, migrations
• Storage Options -- UserDefaults, @AppStorage, FileManager, Keychain, iCloud KVS, SQLite/GRDB