CloudKit

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.

Contents

• Workflow
• Route by Task
• Core Decisions
• Common Mistakes
• Review Checklist
• References

Workflow

1. Choose container, public/private/shared database, record ownership, zone strategy, and offline expectations.
2. Define stable record types, identifiers, references, assets, and conflict fields before writing CRUD code.
3. Use queries for bounded reads and CKSyncEngine or change tokens for durable incremental synchronization.
4. Handle account changes, partial failures, rate limits, retries, conflicts, deletions, and local persistence explicitly.
5. Verify offline edits, concurrent devices, account switching, quota, schema deployment, sharing, and production environment behavior.

Route by Task

• Read core implementation details for containers, records, queries, subscriptions, CKSyncEngine, SwiftData, key-value storage, iCloud Drive, and error handling.
• Read extended CloudKit patterns for change tokens, shares, assets, batch operations, custom zones, and Dashboard procedures.

Core Decisions

• Treat record saves as conflict-prone distributed writes, not local CRUD.
• Persist sync state/change tokens and recover from token expiration.
• Inspect per-item errors in partial failures and honor retry guidance.
• Keep SwiftData CloudKit configuration constraints separate from direct CloudKit workflows.

Common Mistakes

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
• Custom record zones created in private DB; shared DB zones discovered from shares
• CKError.serverRecordChanged handled with three-way merge into serverRecord
• Network failures queued for retry; retryAfterSeconds respected
• CKDatabaseSubscription or CKSyncEngine used for push-based sync; Remote notifications enabled for background delivery
• 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 review reports model compatibility and schema rollout: initialized/verified development schema, promoted before release, and additive-only production changes
• NSUbiquitousKeyValueStore.didChangeExternallyNotification observed
• Encryption review says CKRecord.Reference cannot use encryptedValues because CloudKit needs it server-side; no query/sort on encrypted fields; CKAsset is encrypted by default
• CKSyncEngine state serialization persisted across launches (iOS 17+)

References

• See references/cloudkit-patterns.md for incremental sync, CKShare, zones, CKAsset storage, batch operations, and Dashboard usage.
• CloudKit Framework
• CKContainer
• CKRecord
• CKQuery
• CKSubscription
• CKSyncEngine
• CKShare
• CKError
• NSUbiquitousKeyValueStore
• SwiftData CloudKit sync
• Core implementation details -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.