cloudkit

What it does

Guides developers to implement, review, or improve CloudKit and iCloud synchronization in iOS/macOS apps. It includes setup for CKContainer and databases, CRUD operations for CKRecord, querying with CKQuery, subscriptions, CKSyncEngine usage (iOS 17+), SwiftData integration via ModelConfiguration, NSUbiquitousKeyValueStore, iCloud Drive file coordination, account status checks, and error handling with CKError mapping. It also prescribes conflict resolution strategies and outlines common mistakes and a review checklist.

How it works

• Load appropriate database scope and verify capability, container, account status, schema, and environment before writing records.
• Persist local changes as durable items, enqueue them, and rely on subscriptions or CKSyncEngine to drive remote syncing rather than polling.
• Persist change tokens or sync-engine state after successful operations.
• Test offline edits, partial failures, rate limiting, token expiry, conflicts, account loss, zone deletion, and relaunch scenarios.
• On failure, classify CKError, restore affected items, apply documented retry/reset/merge actions, and rerun the same scenario.
• Use CKSyncEngine for automatic syncing of custom model data; persist stateSerialization to resume correctly.
• When using SwiftData, assess model compatibility and perform schema rollout steps across development and production promotions.
• Handle CKError codes with specific strategies: network failures retry, serverRecordChanged conflict resolution, rate limits retry with delay, quota notifications, and partialFailure per-item inspection.
• Implement conflict resolution by merging client/server/ancestor changes when server records indicate changes.

When to use it

• When configuring CloudKit for iCloud sync across containers and databases.
• When performing CKRecord CRUD, CKQuery, and CKSubscription setup.
• When utilizing CKSyncEngine (iOS 17+) for model data synchronization.
• When integrating CloudKit with SwiftData via ModelConfiguration.
• When using NSUbiquitousKeyValueStore or iCloud Drive file coordination.
• When checking iCloud account status before performing sync operations.
• When handling CKError codes and implementing conflict resolution workflows.

What it can touch

• CKContainer, CKDatabase (public/private/shared), CKRecord, CKQuery, CKSubscription, CKSyncEngine, CKRecordZone, CKRecordZoneSubscription, CKError.
• SwiftData ModelConfiguration and ModelContainer for cloudKitDatabase integration.
• NSUbiquitousKeyValueStore and FileManager ubiquity APIs.
• iCloud account status retrieval via CKContainer.accountStatus().

Caveats

• License is NOASSERTION.
• Requires CloudKit capability and remote notifications for certain features.
• Automatic CKSyncEngine timing is indeterminate and does not guarantee immediate sync.
• Conflict resolution relies on three-way merge logic for serverRecordChanged errors; exact merge behavior is implementation-specific.
• Partial failures require per-item handling and may involve complex retry strategies.