Implement, review, or improve CloudKit and iCloud sync in iOS/macOS apps. Use when working with CKContainer, CKRecord, CKQuery, CKSubscription, CKSyncEngine,…
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
CKRecord CRUD
CKQuery
CKSubscription
CKSyncEngine (iOS 17+)
SwiftData + CloudKit
NSUbiquitousKeyValueStore
iCloud Drive File Sync
Account Status and Error Handling
Conflict Resolution
Common Mistakes
Review Checklist
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
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).
// 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.
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:.
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.
// 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:
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.
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.
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.
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.
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.
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
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.
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.
// 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.
// 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
CKContainer
CKRecord
CKQuery
CKSubscription
CKSyncEngine
CKShare
CKError
NSUbiquitousKeyValueStore
CKAssetdon't have the plugin yet? install it then click "run inline in claude" again.