ios-data

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