---
name: cloudkit-sync
description: "Implement, review, or improve CloudKit and iCloud sync in iOS/macOS apps. Use when working with CKContainer, CKRecord, CKQuery, CKSubscription, CKSyncEngine, CKShare, NSUbiquitousKeyValueStore, or iCloud Drive file coordination; when syncing SwiftData models via ModelConfiguration with cloudKitDatabase; when handling CKError codes for conflict resolution, network failures, or quota limits; or when checking iCloud account status before performing sync operations."
---

# CloudKit and iCloud Sync

Sync data across devices using CloudKit, iCloud key-value storage, and iCloud
Drive. Covers container setup, record CRUD, queries, subscriptions, CKSyncEngine,
SwiftData integration, conflict resolution, and error handling. Targets iOS 26+
with Swift 6.2; older availability noted where relevant.

## Contents

- [Container and Database Setup](#container-and-database-setup)
- [CKRecord CRUD](#ckrecord-crud)
- [CKQuery](#ckquery)
- [CKSubscription](#cksubscription)
- [CKSyncEngine (iOS 17+)](#cksyncengine-ios-17)
- [SwiftData + CloudKit](#swiftdata--cloudkit)
- [NSUbiquitousKeyValueStore](#nsubiquitouskeyvaluestore)
- [iCloud Drive File Sync](#icloud-drive-file-sync)
- [Account Status and Error Handling](#account-status-and-error-handling)
- [Conflict Resolution](#conflict-resolution)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Container and Database Setup

Enable iCloud + CloudKit in Signing & Capabilities. A container provides
three databases:

| Database | Scope | Requires iCloud | Storage Quota |
|----------|-------|-----------------|---------------|
| Public   | All users | Read: No, Write: Yes | App quota |
| Private  | Current user | Yes | User quota |
| Shared   | Shared records | Yes | Owner quota |

```swift
import CloudKit

let container = CKContainer.default()
// Or named: CKContainer(identifier: "iCloud.com.example.app")

let publicDB  = container.publicCloudDatabase
let privateDB = container.privateCloudDatabase
let sharedDB  = container.sharedCloudDatabase
```

## CKRecord CRUD

Records are key-value pairs. Max 1 MB per record (excluding CKAsset data).

```swift
// CREATE
let record = CKRecord(recordType: "Note")
record["title"] = "Meeting Notes" as CKRecordValue
record["body"] = "Discussed Q3 roadmap" as CKRecordValue
record["createdAt"] = Date() as CKRecordValue
record["tags"] = ["work", "planning"] as CKRecordValue
let saved = try await privateDB.save(record)

// FETCH by ID
let recordID = CKRecord.ID(recordName: "unique-id-123")
let fetched = try await privateDB.record(for: recordID)

// UPDATE -- fetch first, modify, then save
fetched["title"] = "Updated Title" as CKRecordValue
let updated = try await privateDB.save(fetched)

// DELETE
try await privateDB.deleteRecord(withID: recordID)
```

### Custom Record Zones (Private/Shared Only)

Custom zones support atomic commits, change tracking, and sharing.

```swift
let zoneID = CKRecordZone.ID(zoneName: "NotesZone")
let zone = CKRecordZone(zoneID: zoneID)
try await privateDB.save(zone)

let recordID = CKRecord.ID(recordName: UUID().uuidString, zoneID: zoneID)
let record = CKRecord(recordType: "Note", recordID: recordID)
```

## CKQuery

Query records with NSPredicate. Supported: `==`, `!=`, `<`, `>`, `<=`, `>=`,
`BEGINSWITH`, `CONTAINS`, `IN`, `AND`, `NOT`, `BETWEEN`,
`distanceToLocation:fromLocation:`.

```swift
let predicate = NSPredicate(format: "title BEGINSWITH %@", "Meeting")
let query = CKQuery(recordType: "Note", predicate: predicate)
query.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]

let (results, _) = try await privateDB.records(matching: query)
for (_, result) in results {
    let record = try result.get()
    print(record["title"] as? String ?? "")
}

// Fetch all records of a type
let allQuery = CKQuery(recordType: "Note", predicate: NSPredicate(value: true))

// Full-text search across string fields
let searchQuery = CKQuery(
    recordType: "Note",
    predicate: NSPredicate(format: "self CONTAINS %@", "roadmap")
)

// Compound predicate
let compound = NSCompoundPredicate(andPredicateWithSubpredicates: [
    NSPredicate(format: "createdAt > %@", cutoffDate as NSDate),
    NSPredicate(format: "tags CONTAINS %@", "work")
])
```

## CKSubscription

Subscriptions trigger push notifications when records change server-side.
CloudKit auto-enables APNs -- no explicit push entitlement needed.

```swift
// Query subscription -- fires when matching records change
let subscription = CKQuerySubscription(
    recordType: "Note",
    predicate: NSPredicate(format: "tags CONTAINS %@", "urgent"),
    subscriptionID: "urgent-notes",
    options: [.firesOnRecordCreation, .firesOnRecordUpdate]
)
let notifInfo = CKSubscription.NotificationInfo()
notifInfo.shouldSendContentAvailable = true  // silent push
subscription.notificationInfo = notifInfo
try await privateDB.save(subscription)

// Database subscription -- fires on any database change
let dbSub = CKDatabaseSubscription(subscriptionID: "private-db-changes")
dbSub.notificationInfo = notifInfo
try await privateDB.save(dbSub)

// Record zone subscription -- fires on changes within a zone
let zoneSub = CKRecordZoneSubscription(
    zoneID: CKRecordZone.ID(zoneName: "NotesZone"),
    subscriptionID: "notes-zone-changes"
)
zoneSub.notificationInfo = notifInfo
try await privateDB.save(zoneSub)
```

Handle in AppDelegate:

```swift
func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    let notification = CKNotification(fromRemoteNotificationDictionary: userInfo)
    guard notification?.subscriptionID == "private-db-changes" else { return .noData }
    // Fetch changes using CKSyncEngine or CKFetchRecordZoneChangesOperation
    return .newData
}
```

## CKSyncEngine (iOS 17+)

`CKSyncEngine` is the recommended sync approach. It handles scheduling,
transient error retries, change tokens, and push notifications automatically.
Works with private and shared databases only.

```swift
import CloudKit

final class SyncManager: CKSyncEngineDelegate {
    let syncEngine: CKSyncEngine

    init(container: CKContainer = .default()) {
        let config = CKSyncEngine.Configuration(
            database: container.privateCloudDatabase,
            stateSerialization: Self.loadState(),
            delegate: self
        )
        self.syncEngine = CKSyncEngine(config)
    }

    func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) {
        switch event {
        case .stateUpdate(let update):
            Self.saveState(update.stateSerialization)
        case .accountChange(let change):
            handleAccountChange(change)
        case .fetchedRecordZoneChanges(let changes):
            for mod in changes.modifications { processRemoteRecord(mod.record) }
            for del in changes.deletions { processRemoteDeletion(del.recordID) }
        case .sentRecordZoneChanges(let sent):
            for saved in sent.savedRecords { markSynced(saved) }
            for fail in sent.failedRecordSaves { handleSaveFailure(fail) }
        default: break
        }
    }

    func nextRecordZoneChangeBatch(
        _ context: CKSyncEngine.SendChangesContext,
        syncEngine: CKSyncEngine
    ) -> CKSyncEngine.RecordZoneChangeBatch? {
        let pending = syncEngine.state.pendingRecordZoneChanges
        return CKSyncEngine.RecordZoneChangeBatch(
            pendingChanges: Array(pending)
        ) { recordID in self.recordToSend(for: recordID) }
    }
}

// Schedule changes
let zoneID = CKRecordZone.ID(zoneName: "NotesZone")
let recordID = CKRecord.ID(recordName: noteID, zoneID: zoneID)
syncEngine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])

// Trigger immediate sync (pull-to-refresh)
try await syncEngine.fetchChanges()
try await syncEngine.sendChanges()
```

**Key point**: persist `stateSerialization` across launches; the engine needs it
to resume from the correct change token.

## SwiftData + CloudKit

`ModelConfiguration` supports CloudKit sync. CloudKit models must use optional
properties and avoid unique constraints.

```swift
import SwiftData

@Model
class Note {
    var title: String
    var body: String?
    var createdAt: Date?
    @Attribute(.externalStorage) var imageData: Data?

    init(title: String, body: String? = nil) {
        self.title = title
        self.body = body
        self.createdAt = Date()
    }
}

let config = ModelConfiguration(
    "Notes",
    cloudKitDatabase: .private("iCloud.com.example.app")
)
let container = try ModelContainer(for: Note.self, configurations: config)
```

**CloudKit model rules**: use optionals for all non-String properties; avoid
`#Unique`; keep models flat; use `@Attribute(.externalStorage)` for large data;
avoid complex relationship graphs.

## NSUbiquitousKeyValueStore

Simple key-value sync. Max 1024 keys, 1 MB total, 1 MB per value. Stores
locally when iCloud is unavailable.

```swift
let kvStore = NSUbiquitousKeyValueStore.default

// Write
kvStore.set("dark", forKey: "theme")
kvStore.set(14.0, forKey: "fontSize")
kvStore.set(true, forKey: "notificationsEnabled")
kvStore.synchronize()

// Read
let theme = kvStore.string(forKey: "theme") ?? "system"

// Observe external changes
NotificationCenter.default.addObserver(
    forName: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
    object: kvStore, queue: .main
) { notification in
    guard let userInfo = notification.userInfo,
          let reason = userInfo[NSUbiquitousKeyValueStoreChangeReasonKey] as? Int,
          let keys = userInfo[NSUbiquitousKeyValueStoreChangedKeysKey] as? [String]
    else { return }

    switch reason {
    case NSUbiquitousKeyValueStoreServerChange:
        for key in keys { applyRemoteChange(key: key) }
    case NSUbiquitousKeyValueStoreInitialSyncChange:
        reloadAllSettings()
    case NSUbiquitousKeyValueStoreQuotaViolationChange:
        handleQuotaExceeded()
    default: break
    }
}
```

## iCloud Drive File Sync

Use `FileManager` ubiquity APIs for document-level sync.

```swift
guard let ubiquityURL = FileManager.default.url(
    forUbiquityContainerIdentifier: "iCloud.com.example.app"
) else { return }  // iCloud not available

let docsURL = ubiquityURL.appendingPathComponent("Documents")
let cloudURL = docsURL.appendingPathComponent("report.pdf")
try FileManager.default.setUbiquitous(true, itemAt: localURL, destinationURL: cloudURL)

// Monitor iCloud files
let query = NSMetadataQuery()
query.predicate = NSPredicate(format: "%K LIKE '*.pdf'", NSMetadataItemFSNameKey)
query.searchScopes = [NSMetadataQueryUbiquitousDocumentsScope]
NotificationCenter.default.addObserver(
    forName: .NSMetadataQueryDidFinishGathering, object: query, queue: .main
) { _ in
    query.disableUpdates()
    for item in query.results as? [NSMetadataItem] ?? [] {
        let name = item.value(forAttribute: NSMetadataItemFSNameKey) as? String
        let status = item.value(
            forAttribute: NSMetadataUbiquitousItemDownloadingStatusKey) as? String
    }
    query.enableUpdates()
}
query.start()
```

## Account Status and Error Handling

Always check account status before sync. Listen for `.CKAccountChanged`.

```swift
func checkiCloudStatus() async throws -> CKAccountStatus {
    let status = try await CKContainer.default().accountStatus()
    switch status {
    case .available: return status
    case .noAccount: throw SyncError.noiCloudAccount
    case .restricted: throw SyncError.restricted
    case .temporarilyUnavailable: throw SyncError.temporarilyUnavailable
    case .couldNotDetermine: throw SyncError.unknown
    @unknown default: throw SyncError.unknown
    }
}
```

### CKError Handling

| Error Code | Strategy |
|-----------|----------|
| `.networkFailure`, `.networkUnavailable` | Queue for retry when network returns |
| `.serverRecordChanged` | Three-way merge (see Conflict Resolution) |
| `.requestRateLimited`, `.zoneBusy`, `.serviceUnavailable` | Retry after `retryAfterSeconds` |
| `.quotaExceeded` | Notify user; reduce data usage |
| `.notAuthenticated` | Prompt iCloud sign-in |
| `.partialFailure` | Inspect `partialErrorsByItemID` per item |
| `.changeTokenExpired` | Reset token, refetch all changes |
| `.userDeletedZone` | Recreate zone and re-upload data |

```swift
func handleCloudKitError(_ error: Error) {
    guard let ckError = error as? CKError else { return }
    switch ckError.code {
    case .networkFailure, .networkUnavailable:
        scheduleRetryWhenOnline()
    case .serverRecordChanged:
        resolveConflict(ckError)
    case .requestRateLimited, .zoneBusy, .serviceUnavailable:
        let delay = ckError.retryAfterSeconds ?? 3.0
        scheduleRetry(after: delay)
    case .quotaExceeded:
        notifyUserStorageFull()
    case .partialFailure:
        if let partial = ckError.partialErrorsByItemID {
            for (_, itemError) in partial { handleCloudKitError(itemError) }
        }
    case .changeTokenExpired:
        resetChangeToken()
    case .userDeletedZone:
        recreateZoneAndResync()
    default: logError(ckError)
    }
}
```

## Conflict Resolution

When saving a record that changed server-side, CloudKit returns
`.serverRecordChanged` with three record versions. Always merge into
`serverRecord` -- it has the correct change tag.

```swift
func resolveConflict(_ error: CKError) {
    guard error.code == .serverRecordChanged,
          let ancestor = error.ancestorRecord,
          let client = error.clientRecord,
          let server = error.serverRecord
    else { return }

    // Merge client changes into server record
    for key in client.changedKeys() {
        if server[key] == ancestor[key] {
            server[key] = client[key]           // Server unchanged, use client
        } else if client[key] == ancestor[key] {
            // Client unchanged, keep server (already there)
        } else {
            server[key] = mergeValues(          // Both changed, custom merge
                ancestor: ancestor[key], client: client[key], server: server[key])
        }
    }

    Task { try await CKContainer.default().privateCloudDatabase.save(server) }
}
```

## Common Mistakes

**DON'T:** Perform sync operations without checking account status.
**DO:** Check `CKContainer.accountStatus()` first; handle `.noAccount`.
```swift
// WRONG
try await privateDB.save(record)
// CORRECT
guard try await CKContainer.default().accountStatus() == .available
else { throw SyncError.noiCloudAccount }
try await privateDB.save(record)
```

**DON'T:** Ignore `.serverRecordChanged` errors.
**DO:** Implement three-way merge using ancestor, client, and server records.

**DON'T:** Store user-specific data in the public database.
**DO:** Use private database for personal data; public only for app-wide content.

**DON'T:** Assume data is available immediately after save.
**DO:** Update local cache optimistically and reconcile on fetch.

**DON'T:** Poll for changes on a timer.
**DO:** Use `CKDatabaseSubscription` or `CKSyncEngine` for push-based sync.
```swift
// WRONG
Timer.scheduledTimer(withTimeInterval: 30, repeats: true) { _ in fetchAll() }
// CORRECT
let sub = CKDatabaseSubscription(subscriptionID: "db-changes")
sub.notificationInfo = CKSubscription.NotificationInfo()
sub.notificationInfo?.shouldSendContentAvailable = true
try await privateDB.save(sub)
```

**DON'T:** Retry immediately on rate limiting.
**DO:** Use `CKError.retryAfterSeconds` to wait the required duration.

**DON'T:** Merge conflict changes into `clientRecord`.
**DO:** Always merge into `serverRecord` -- it has the correct change tag.

**DON'T:** Pass nil change token on every fetch.
**DO:** Persist change tokens to disk and supply them on subsequent fetches.

## Review Checklist

- [ ] iCloud + CloudKit capability enabled in Signing & Capabilities
- [ ] Account status checked before sync; `.noAccount` handled gracefully
- [ ] Private database used for user data; public only for shared content
- [ ] `CKError.serverRecordChanged` handled with three-way merge into `serverRecord`
- [ ] Network failures queued for retry; `retryAfterSeconds` respected
- [ ] `CKDatabaseSubscription` or `CKSyncEngine` used for push-based sync
- [ ] Change tokens persisted to disk; `changeTokenExpired` resets and refetches
- [ ] `.partialFailure` errors inspected per-item via `partialErrorsByItemID`
- [ ] `.userDeletedZone` handled by recreating zone and resyncing
- [ ] SwiftData CloudKit models use optionals, no `#Unique`, `.externalStorage` for large data
- [ ] `NSUbiquitousKeyValueStore.didChangeExternallyNotification` observed
- [ ] Sensitive data uses `encryptedValues` on CKRecord (not plain fields)
- [ ] `CKSyncEngine` state serialization persisted across launches (iOS 17+)

## References

- See `references/cloudkit-patterns.md` for CKFetchRecordZoneChangesOperation
  incremental sync, CKShare collaboration, record zone management, CKAsset
  file storage, batch operations, and CloudKit Dashboard usage.
- [CloudKit Framework](https://sosumi.ai/documentation/cloudkit)
- [CKContainer](https://sosumi.ai/documentation/cloudkit/ckcontainer)
- [CKRecord](https://sosumi.ai/documentation/cloudkit/ckrecord)
- [CKQuery](https://sosumi.ai/documentation/cloudkit/ckquery)
- [CKSubscription](https://sosumi.ai/documentation/cloudkit/cksubscription)
- [CKSyncEngine](https://sosumi.ai/documentation/cloudkit/cksyncengine)
- [CKShare](https://sosumi.ai/documentation/cloudkit/ckshare)
- [CKError](https://sosumi.ai/documentation/cloudkit/ckerror)
- [NSUbiquitousKeyValueStore](https://sosumi.ai/documentation/foundation/nsubiquitouskeyvaluestore)
- [CKAsset](https://sosumi.ai/documentation/cloudkit/ckasset)