---
name: axiom-cloud-sync
description: Use when choosing between CloudKit vs iCloud Drive, implementing reliable sync, handling offline-first patterns, or designing sync architecture - prevents common sync mistakes that cause data loss
license: MIT
compatibility: iOS 10+, macOS 10.12+
metadata:
  version: "1.0.0"
  last-updated: "2025-12-25"
---

# Cloud Sync

## Overview

**Core principle**: Choose the right sync technology for the data shape, then implement offline-first patterns that handle network failures gracefully.

Two fundamentally different sync approaches:
- **CloudKit** — Structured data (records with fields and relationships)
- **iCloud Drive** — File-based data (documents, images, any file format)

## Quick Decision Tree

```
What needs syncing?

├─ Structured data (records, relationships)?
│  ├─ Using SwiftData? → SwiftData + CloudKit (easiest, iOS 17+)
│  ├─ Need shared/public database? → CKSyncEngine or raw CloudKit
│  └─ Custom persistence (GRDB, SQLite)? → CKSyncEngine (iOS 17+)
│
├─ Documents/files users expect in Files app?
│  └─ iCloud Drive (UIDocument or FileManager)
│
├─ Large binary blobs (images, videos)?
│  ├─ Associated with structured data? → CKAsset in CloudKit
│  └─ Standalone files? → iCloud Drive
│
└─ App settings/preferences?
   └─ NSUbiquitousKeyValueStore (simple key-value, 1MB limit)
```

## CloudKit vs iCloud Drive

| Aspect | CloudKit | iCloud Drive |
|--------|----------|--------------|
| **Data shape** | Structured records | Files/documents |
| **Query support** | Full query language | Filename only |
| **Relationships** | Native support | None (manual) |
| **Conflict resolution** | Record-level | File-level |
| **User visibility** | Hidden from user | Visible in Files app |
| **Sharing** | Record/database sharing | File sharing |
| **Offline** | Local cache required | Automatic download |

## Red Flags

If ANY of these appear, STOP and reconsider:

- ❌ "Store JSON files in CloudKit" — Wrong tool. Use iCloud Drive for files
- ❌ "Build relationships manually in iCloud Drive" — Wrong tool. Use CloudKit
- ❌ "Assume sync is instant" — Network fails. Design offline-first
- ❌ "Skip conflict handling" — Conflicts WILL happen on multiple devices
- ❌ "Use CloudKit for user documents" — Users can't see them. Use iCloud Drive
- ❌ "Sync on app launch only" — Users expect continuous sync

## Offline-First Pattern

**MANDATORY**: All sync code must work offline first.

```swift
// ✅ CORRECT: Offline-first architecture
class OfflineFirstSync {
    private let localStore: LocalDatabase  // GRDB, SwiftData, Core Data
    private let syncEngine: CKSyncEngine

    // Write to LOCAL first, sync to cloud in background
    func save(_ item: Item) async throws {
        // 1. Save locally (instant)
        try await localStore.save(item)

        // 2. Queue for sync (non-blocking)
        syncEngine.state.add(pendingRecordZoneChanges: [
            .saveRecord(item.recordID)
        ])
    }

    // Read from LOCAL (instant)
    func fetch() async throws -> [Item] {
        return try await localStore.fetchAll()
    }
}

// ❌ WRONG: Cloud-first (blocks on network)
func save(_ item: Item) async throws {
    // Fails when offline, slow on bad network
    try await cloudKit.save(item)
    try await localStore.save(item)
}
```

## Conflict Resolution Strategies

Conflicts occur when two devices edit the same data before syncing.

### Strategy 1: Last-Writer-Wins (Simplest)

```swift
// Server always has latest, client accepts it
func resolveConflict(local: CKRecord, server: CKRecord) -> CKRecord {
    return server  // Accept server version
}
```

**Use when**: Data is non-critical, user won't notice overwrites

### Strategy 2: Merge (Most Common)

```swift
// Combine changes from both versions
func resolveConflict(local: CKRecord, server: CKRecord) -> CKRecord {
    let merged = server.copy() as! CKRecord

    // For each field, apply custom merge logic
    merged["notes"] = mergeText(
        local["notes"] as? String,
        server["notes"] as? String
    )
    merged["tags"] = mergeSets(
        local["tags"] as? [String] ?? [],
        server["tags"] as? [String] ?? []
    )

    return merged
}
```

**Use when**: Both versions contain valuable changes

### Strategy 3: User Choice

```swift
// Present conflict to user
func resolveConflict(local: CKRecord, server: CKRecord) async -> CKRecord {
    let choice = await presentConflictUI(local: local, server: server)
    return choice == .keepLocal ? local : server
}
```

**Use when**: Data is critical, user must decide

## Common Patterns

### Pattern 1: SwiftData + CloudKit (Recommended for New Apps)

```swift
import SwiftData

// Automatic CloudKit sync with zero configuration
@Model
class Note {
    var title: String
    var content: String
    var createdAt: Date

    init(title: String, content: String) {
        self.title = title
        self.content = content
        self.createdAt = Date()
    }
}

// Container automatically syncs if CloudKit entitlement present
let container = try ModelContainer(for: Note.self)
```

**Limitations**:
- Private database only (no public/shared)
- Automatic sync (less control over timing)
- No custom conflict resolution
- `@Attribute(.unique)` not supported with CloudKit sync — remove if using CloudKit

### Pattern 2: CKSyncEngine (Custom Persistence)

```swift
// For GRDB, SQLite, or custom databases
class MySyncManager: CKSyncEngineDelegate {
    private let engine: CKSyncEngine
    private let database: GRDBDatabase

    func handleEvent(_ event: CKSyncEngine.Event) async {
        switch event {
        case .stateUpdate(let update):
            // Persist sync state
            await saveSyncState(update.stateSerialization)

        case .fetchedDatabaseChanges(let changes):
            // Apply changes to local DB
            for zone in changes.modifications {
                await handleZoneChanges(zone)
            }

        case .sentRecordZoneChanges(let sent):
            // Mark records as synced
            for saved in sent.savedRecords {
                await markSynced(saved.recordID)
            }
        }
    }
}
```

See `axiom-cloudkit-ref` for complete CKSyncEngine setup.

### Pattern 3: iCloud Drive Documents

```swift
import UIKit

class MyDocument: UIDocument {
    var content: Data?

    override func contents(forType typeName: String) throws -> Any {
        return content ?? Data()
    }

    override func load(fromContents contents: Any, ofType typeName: String?) throws {
        content = contents as? Data
    }
}

// Save to iCloud Drive (visible in Files app)
let url = FileManager.default.url(forUbiquityContainerIdentifier: nil)?
    .appendingPathComponent("Documents")
    .appendingPathComponent("MyFile.txt")

let doc = MyDocument(fileURL: url!)
doc.content = "Hello".data(using: .utf8)
doc.save(to: url!, for: .forCreating)
```

See `axiom-icloud-drive-ref` for NSFileCoordinator and conflict handling.

## Anti-Patterns

### 1. Ignoring Sync State

```swift
// ❌ WRONG: No awareness of pending changes
var items: [Item] = []  // Are these synced? Pending? Conflicted?

// ✅ CORRECT: Track sync state
struct SyncableItem {
    let item: Item
    let syncState: SyncState  // .synced, .pending, .conflict
}
```

### 2. Blocking UI on Sync

```swift
// ❌ WRONG: UI blocks until sync completes
func viewDidLoad() async {
    items = try await cloudKit.fetchAll()  // Spinner forever on airplane
    tableView.reloadData()
}

// ✅ CORRECT: Show local data immediately
func viewDidLoad() {
    items = localStore.fetchAll()  // Instant
    tableView.reloadData()

    Task {
        await syncEngine.fetchChanges()  // Background update
    }
}
```

### 3. CloudKit Schema Not Deployed to Production

CloudKit has **separate schemas for Development and Production**. Your app in the App Store can only access the Production environment. If you add record types, fields, or indexes in Development but never deploy them, queries in Production return empty results with no error.

```
❌ Works in Xcode/TestFlight (Development) → empty results in App Store (Production)
   Queries silently return zero results — no CKError, no crash, no clue.

✅ Before every App Store submission:
   1. CloudKit Console → Select container
   2. "Deploy Schema Changes" → Review changes → Deploy
   3. Test with Production environment in Xcode scheme settings
```

**Time cost of skipping**: 3-7 days (rejection cycle + debugging "why does it work in TestFlight but not production?"). This is the #1 CloudKit gotcha for first-time submitters.

### 4. No Retry Logic

```swift
// ❌ WRONG: Single attempt
try await cloudKit.save(record)

// ✅ CORRECT: Exponential backoff
func saveWithRetry(_ record: CKRecord, attempts: Int = 3) async throws {
    for attempt in 0..<attempts {
        do {
            try await cloudKit.save(record)
            return
        } catch let error as CKError where error.isRetryable {
            let delay = pow(2.0, Double(attempt))
            try await Task.sleep(for: .seconds(delay))
        }
    }
    throw SyncError.maxRetriesExceeded
}
```

## Sync State Indicators

Always show users the sync state:

```swift
enum SyncState {
    case synced       // ✓ (checkmark)
    case pending      // ↻ (arrows)
    case conflict     // ⚠ (warning)
    case offline      // ☁ with X
}

// In SwiftUI
HStack {
    Text(item.title)
    Spacer()
    SyncIndicator(state: item.syncState)
}
```

## Entitlement Checklist

Before sync will work:

1. **Xcode → Signing & Capabilities**
   - ✓ iCloud capability added
   - ✓ CloudKit checked (for CloudKit)
   - ✓ iCloud Documents checked (for iCloud Drive)
   - ✓ Container selected/created

2. **Apple Developer Portal**
   - ✓ App ID has iCloud capability
   - ✓ CloudKit container exists (for CloudKit)

3. **CloudKit Console (before App Store submission)**
   - ✓ Schema deployed to Production (record types, fields, indexes)
   - ✓ Test with Production environment in Xcode scheme to verify queries work

4. **Device**
   - ✓ Signed into iCloud
   - ✓ iCloud Drive enabled (Settings → [Name] → iCloud)

## Large Dataset Sync

When syncing 10,000+ records, naive approaches cause timeouts and launch slowdowns.

### Initial Sync Strategy

```swift
// ❌ WRONG: Fetch everything at once
let allRecords = try await database.fetchAll()
syncEngine.state.add(pendingRecordZoneChanges: allRecords.map { .saveRecord($0.recordID) })

// ✅ CORRECT: Batch initial sync
func performInitialSync(batchSize: Int = 200) async throws {
    var cursor: CKQueryOperation.Cursor? = nil

    repeat {
        let (results, nextCursor) = try await database.records(
            matching: query,
            resultsLimit: batchSize,
            desiredKeys: nil,
            continuationCursor: cursor
        )
        // Process batch
        try await localStore.saveBatch(results.compactMap { try? $0.1.get() })
        cursor = nextCursor
    } while cursor != nil
}
```

### Incremental Sync (After Initial)

CKSyncEngine handles incremental sync automatically — it fetches only changes since the last sync token. Ensure you persist `stateSerialization` so the engine doesn't re-fetch everything on next launch.

### Performance Guidelines

| Dataset Size | Strategy | Notes |
|-------------|----------|-------|
| < 1,000 records | Default CKSyncEngine | Works out of the box |
| 1,000–10,000 | Batch initial sync | 200-record batches, show progress UI |
| 10,000+ | Pagination + background | Use BGProcessingTask for initial sync |
| 100,000+ | Server-side filtering | Only sync what user needs, lazy-load rest |

**Key insight**: Initial sync is the bottleneck. After initial sync, CKSyncEngine's incremental approach handles large datasets efficiently because it only fetches deltas.

## Pressure Scenarios

### Scenario 1: "Just skip conflict handling for v1"

**Situation**: Deadline pressure to ship without conflict resolution.

**Risk**: Users WILL edit on multiple devices. Data WILL be lost silently.

**Response**: "Minimum viable conflict handling takes 2 hours. Silent data loss costs users and generates 1-star reviews."

### Scenario 2: "Sync on app launch is enough"

**Situation**: Avoiding continuous sync complexity.

**Risk**: Users expect changes to appear within seconds, not on next launch.

**Response**: Use CKSyncEngine or SwiftData which handle continuous sync automatically.

## Related Skills

- `axiom-cloudkit-ref` — Complete CloudKit API reference
- `axiom-icloud-drive-ref` — File-based sync with NSFileCoordinator
- `axiom-cloud-sync-diag` — Debugging sync failures
- `axiom-storage` — Choosing where to store data locally