iOS Storage Guide
Purpose: Navigation hub for ALL storage decisions — database vs files, local vs cloud, specific locations iOS Version: iOS 17+ (iOS 26+ for latest features) Context: Complete storage decision framework integrating SwiftData (WWDC 2023), CKSyncEngine (WWDC 2023), and file management best practices
When to Use This Skill
✅ Use this skill when:
Starting a new project and choosing storage approach Asking "where should I store this data?" Deciding between SwiftData, Core Data, SQLite, or files Choosing between CloudKit and iCloud Drive for sync Determining Documents vs Caches vs Application Support Planning data architecture for offline/online scenarios Migrating from one storage solution to another Debugging "files disappeared" or "data not syncing"
❌ Do NOT use this skill for:
SwiftData implementation details (use axiom-swiftdata skill) SQLite/GRDB specifics (use axiom-sqlitedata or axiom-grdb skills) CloudKit sync implementation (use axiom-cloudkit-ref skill) File protection APIs (use axiom-file-protection-ref skill)
Related Skills:
Existing database skills: axiom-swiftdata, axiom-sqlitedata, axiom-grdb New file skills: axiom-file-protection-ref, axiom-storage-management-ref, axiom-storage-diag New cloud skills: axiom-cloudkit-ref, axiom-icloud-drive-ref, axiom-cloud-sync-diag Core Philosophy
"Choose the right tool for your data shape. Then choose the right location."
Storage decisions have two dimensions:
Format: How is data structured? (Queryable records vs files) Location: Where is it stored? (Local vs cloud, which directory)
Getting the format wrong forces workarounds. Getting the location wrong causes data loss or backup bloat.
The Complete Decision Tree Level 1: Format — What Are You Storing? What is the shape of your data?
├─ STRUCTURED DATA (queryable records, relationships, search) │ Examples: User profiles, task lists, notes, contacts, transactions │ → Continue to "Structured Data Path" below │ └─ FILES (documents, images, videos, downloads, caches) Examples: Photos, PDFs, downloaded content, thumbnails, temp files → Continue to "File Storage Path" below
Structured Data Path Modern Apps (iOS 17+) // ✅ CORRECT: SwiftData for modern structured persistence import SwiftData
@Model class Task { var title: String var isCompleted: Bool var dueDate: Date
init(title: String, isCompleted: Bool = false, dueDate: Date) {
self.title = title
self.isCompleted = isCompleted
self.dueDate = dueDate
}
}
// Query with type safety @Query(sort: \Task.dueDate) var tasks: [Task]
Why SwiftData:
Modern Swift-native API (no Objective-C) Type-safe queries Built-in CloudKit sync support Observable models integrate with SwiftUI Use skill: axiom-swiftdata for implementation details
When NOT to use SwiftData:
Need advanced SQLite features (FTS5, complex joins) Existing Core Data app (migration overhead) Ultra-performance-critical (direct SQLite is faster) Advanced Control Needed // ✅ CORRECT: SQLiteData or GRDB for advanced features import SQLiteData
// Full-text search, custom indices, raw SQL when needed let results = try db.prepare("SELECT * FROM users WHERE name MATCH ?", "John")
Use SQLiteData when:
Need full-text search (FTS5) Custom SQL queries and indices Maximum performance (direct SQLite) Migration from existing SQLite database Use skill: axiom-sqlitedata for modern SQLite patterns
Use GRDB when:
Need reactive queries (ValueObservation) Complex database operations Type-safe query builders Use skill: axiom-grdb for advanced patterns Legacy Apps (iOS 16 and earlier) // ❌ LEGACY: Core Data (avoid for new projects) import CoreData
// NSManagedObject, NSFetchRequest, NSPredicate...
Only use Core Data if:
Maintaining existing Core Data app Can't upgrade to iOS 17 minimum deployment File Storage Path Decision Tree for Files What kind of file is it?
├─ USER-CREATED CONTENT (documents, photos created by user) │ Where: Documents/ directory │ Backed up: ✅ Yes (iCloud/iTunes) │ Purged: ❌ Never │ Visible in Files app: ✅ Yes │ Example: User's edited photos, documents, exported data │ → See "Documents Directory" section below │ ├─ APP-GENERATED DATA (not user-visible, must persist) │ Where: Library/Application Support/ │ Backed up: ✅ Yes │ Purged: ❌ Never │ Visible in Files app: ❌ No │ Example: Database files, user settings, downloaded assets │ → See "Application Support Directory" section below │ ├─ RE-DOWNLOADABLE / REGENERABLE CONTENT │ Where: Library/Caches/ │ Backed up: ❌ No (set isExcludedFromBackup) │ Purged: ✅ Yes (under storage pressure) │ Example: Thumbnails, API responses, downloaded images │ → See "Caches Directory" section below │ └─ TEMPORARY FILES (can be deleted anytime) Where: tmp/ Backed up: ❌ No Purged: ✅ Yes (aggressive, even while app running) Example: Image processing intermediates, export staging → See "Temporary Directory" section below
Documents Directory // ✅ CORRECT: User-created content in Documents func saveUserDocument(_ data: Data, filename: String) throws { let documentsURL = FileManager.default.urls( for: .documentDirectory, in: .userDomainMask )[0]
let fileURL = documentsURL.appendingPathComponent(filename)
// Enable file protection
try data.write(to: fileURL, options: .completeFileProtection)
}
Key rules:
✅ DO store: User-created documents, exported files, user-visible content ❌ DON'T store: Downloaded data that can be re-fetched, caches, temp files ⚠️ WARNING: Everything here is backed up to iCloud. Large re-downloadable files will bloat backups and may get your app rejected.
Use skill: axiom-file-protection-ref for encryption options
Application Support Directory // ✅ CORRECT: App data in Application Support func getAppDataURL() -> URL { let appSupportURL = FileManager.default.urls( for: .applicationSupportDirectory, in: .userDomainMask )[0]
// Create app-specific subdirectory
let appDataURL = appSupportURL.appendingPathComponent(
Bundle.main.bundleIdentifier ?? "AppData"
)
try? FileManager.default.createDirectory(
at: appDataURL,
withIntermediateDirectories: true
)
return appDataURL
}
Use for:
SwiftData/SQLite database files User preferences Downloaded assets that must persist Configuration files Caches Directory // ✅ CORRECT: Re-downloadable content in Caches func cacheDownloadedImage(data: Data, for url: URL) throws { let cacheURL = FileManager.default.urls( for: .cachesDirectory, in: .userDomainMask )[0]
let filename = url.lastPathComponent
let fileURL = cacheURL.appendingPathComponent(filename)
try data.write(to: fileURL)
// Mark as excluded from backup (explicit, though Caches is auto-excluded)
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true
try fileURL.setResourceValues(resourceValues)
}
Key rules:
✅ The system CAN and WILL delete files here under storage pressure ✅ Always have a way to re-download or regenerate ❌ Don't store anything that can't be recreated
Use skill: axiom-storage-management-ref for purge policies and disk space management
Temporary Directory // ✅ CORRECT: Truly temporary files in tmp func processImageWithTempFile(image: UIImage) throws { let tmpURL = FileManager.default.temporaryDirectory let tempFileURL = tmpURL.appendingPathComponent(UUID().uuidString + ".jpg")
// Write temp file
try image.jpegData(compressionQuality: 0.8)?.write(to: tempFileURL)
// Process...
processImage(at: tempFileURL)
// Clean up (though system will auto-clean eventually)
try? FileManager.default.removeItem(at: tempFileURL)
}
Key rules:
System can delete files here AT ANY TIME (even while app is running) Always clean up after yourself Don't rely on files persisting between app launches Cloud Storage Decisions Should Data Sync to Cloud? Does this data need to sync across user's devices?
├─ NO → Use local storage (paths above) │ └─ YES → What kind of data? │ ├─ STRUCTURED DATA (queryable, relationships) │ → Use CloudKit │ → See "CloudKit Path" below │ ├─ FILES (documents, images) │ → Use iCloud Drive (ubiquitous containers) │ → See "iCloud Drive Path" below │ └─ SMALL PREFERENCES (<1 MB, key-value pairs) → Use NSUbiquitousKeyValueStore → See "Key-Value Store" below
CloudKit Path (Structured Data Sync) // ✅ CORRECT: SwiftData with CloudKit sync (iOS 17+) import SwiftData
let container = try ModelContainer( for: Task.self, configurations: ModelConfiguration( cloudKitDatabase: .private("iCloud.com.example.app") ) )
Three approaches to CloudKit:
SwiftData + CloudKit (Recommended, iOS 17+):
Automatic sync for SwiftData models Private database only Easiest approach Use skill: axiom-swiftdata for details
CKSyncEngine (Custom persistence, iOS 17+):
For SQLite, GRDB, or custom stores Manages sync automatically Modern replacement for manual CloudKit Use skill: axiom-cloudkit-ref for CKSyncEngine patterns
Raw CloudKit APIs (Legacy):
CKContainer, CKDatabase, CKRecord Manual sync management Only if CKSyncEngine doesn't fit Use skill: axiom-cloudkit-ref for raw API reference iCloud Drive Path (File Sync) // ✅ CORRECT: iCloud Drive for file-based sync func saveToICloud(_ data: Data, filename: String) throws { // Get ubiquitous container guard let iCloudURL = FileManager.default.url( forUbiquityContainerIdentifier: nil ) else { throw StorageError.iCloudUnavailable }
let documentsURL = iCloudURL.appendingPathComponent("Documents")
try FileManager.default.createDirectory(
at: documentsURL,
withIntermediateDirectories: true
)
let fileURL = documentsURL.appendingPathComponent(filename)
try data.write(to: fileURL)
}
When to use iCloud Drive:
User-created documents that sync File-based collaboration Simple file sync (like Dropbox)
Use skill: axiom-icloud-drive-ref for implementation details
Key-Value Store (Small Preferences) // ✅ CORRECT: Small synced preferences let store = NSUbiquitousKeyValueStore.default
store.set(true, forKey: "darkModeEnabled") store.set(2.0, forKey: "textSize") store.synchronize()
Limitations:
Max 1 MB total storage Max 1024 keys Max 1 MB per value For preferences ONLY, not data storage Common Patterns and Anti-Patterns ✅ DO: Choose Based on Data Shape // ✅ CORRECT: Structured data → SwiftData @Model class Note { var title: String var content: String var tags: [Tag] // Relationships }
// ✅ CORRECT: Files → FileManager + proper directory let imageData = capturedPhoto.jpegData(compressionQuality: 0.9) try imageData?.write(to: documentsURL.appendingPathComponent("photo.jpg"))
❌ DON'T: Use Files for Structured Data // ❌ WRONG: Storing queryable data as JSON files let tasks = [Task(...), Task(...), Task(...)] let jsonData = try JSONEncoder().encode(tasks) try jsonData.write(to: appSupportURL.appendingPathComponent("tasks.json"))
// Why it's wrong: // - Can't query individual tasks // - Can't filter or sort efficiently // - No relationships // - Entire file loaded into memory // - Concurrent access issues
// ✅ CORRECT: Use SwiftData instead @Model class Task { ... }
❌ DON'T: Store Re-downloadable Content in Documents // ❌ WRONG: Downloaded images in Documents (bloats backup!) func downloadProfileImage(url: URL) throws { let data = try Data(contentsOf: url) let documentsURL = FileManager.default.urls( for: .documentDirectory, in: .userDomainMask )[0] try data.write(to: documentsURL.appendingPathComponent("profile.jpg")) }
// ✅ CORRECT: Use Caches instead func downloadProfileImage(url: URL) throws { let data = try Data(contentsOf: url) let cacheURL = FileManager.default.urls( for: .cachesDirectory, in: .userDomainMask )[0] let fileURL = cacheURL.appendingPathComponent("profile.jpg") try data.write(to: fileURL)
// Mark excluded from backup
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true
try fileURL.setResourceValues(resourceValues)
}
❌ DON'T: Use CloudKit for Simple File Sync // ❌ WRONG: Storing files as CKAssets with manual sync let asset = CKAsset(fileURL: documentURL) let record = CKRecord(recordType: "Document") record["file"] = asset // ... manual upload, conflict handling, etc.
// ✅ CORRECT: Use iCloud Drive for files // Files automatically sync via ubiquitous container try data.write(to: iCloudDocumentsURL.appendingPathComponent("doc.pdf"))
Quick Reference Table Data Type Format Local Location Cloud Sync Use Skill User tasks, notes Structured Application Support SwiftData + CloudKit axiom-swiftdata → axiom-cloudkit-ref User photos (created) File Documents iCloud Drive axiom-file-protection-ref → axiom-icloud-drive-ref Downloaded images File Caches None (re-download) axiom-storage-management-ref Thumbnails File Caches None (regenerate) axiom-storage-management-ref Database file File Application Support CKSyncEngine (if custom) axiom-sqlitedata → axiom-cloudkit-ref Temp processing File tmp None N/A User settings Key-Value UserDefaults NSUbiquitousKeyValueStore N/A Debugging: Data Missing or Not Syncing?
Files disappeared:
Check if stored in Caches or tmp (system purged them) Check file protection level (may be inaccessible when locked) Use skill: axiom-storage-diag
Backup too large:
Check if re-downloadable content is in Documents (should be in Caches) Check if isExcludedFromBackup is set on large files Use skill: axiom-storage-management-ref
Data not syncing:
CloudKit: Check CKSyncEngine status, account availability Use skill: axiom-cloud-sync-diag iCloud Drive: Check ubiquitous container entitlements, file coordinator Use skill: axiom-icloud-drive-ref, axiom-cloud-sync-diag Migration Checklist
When changing storage approach:
Database to Database (e.g., Core Data → SwiftData):
Create SwiftData models matching Core Data entities Write migration code to copy data Test with production-size datasets Keep old database for rollback
Files to Database:
Identify all JSON/plist files storing structured data Create SwiftData models Write one-time migration on first launch Verify all data migrated, then delete old files
Local to Cloud:
Ensure proper entitlements (CloudKit/iCloud) Handle initial upload carefully (bandwidth) Test conflict resolution Provide user control (opt-in)
Last Updated: 2025-12-12 Skill Type: Discipline Related WWDC Sessions:
WWDC 2023-10187: Meet SwiftData WWDC 2023-10188: Sync to iCloud with CKSyncEngine WWDC 2024-10137: What's new in SwiftData