Cloudkit Code Review

CloudKit Code Review

Quick Reference

Review Checklist

• [ ] Account status checked before private/shared database operations
• [ ] Custom zones used (not default zone) for production data
• [ ] All CloudKit errors handled with retryAfterSeconds respected
• [ ] serverRecordChanged conflicts handled with proper merge logic
• [ ] CKErrorPartialFailure parsed for individual record errors
• [ ] Batch operations used (CKModifyRecordsOperation) not individual saves
• [ ] Large binary data stored as CKAsset (records have 1MB limit)
• [ ] Record keys type-safe (enums) not string literals
• [ ] UI updates dispatched to main thread from callbacks
• [ ] CKAccountChangedNotification observed for account switches
• [ ] Subscriptions have unique IDs to prevent duplicates
• [ ] CKShare uses custom zone (sharing requires custom zones)

When to Load References

• Reviewing container/database setup or zones -> container-setup.md
• Reviewing record CRUD or relationships -> records.md
• Reviewing push notifications or sync triggers -> subscriptions.md
• Reviewing sharing or collaboration features -> sharing.md

Output Format

Report issues using: [FILE:LINE] ISSUE_TITLE

Examples:

• [AppDelegate.swift:24] CKContainer not in custom zone
• [SyncManager.swift:156] Unhandled CKErrorPartialFailure
• [DataStore.swift:89] Missing retryAfterSeconds backoff

Review Questions

1. What happens when the user is signed out of iCloud? 2. Does error handling respect rate limiting (retryAfterSeconds)? 3. Are conflicts resolved or does data get overwritten silently? 4. Is the schema deployed to production before App Store release? 5. Are shared records in custom zones (required for CKShare)?

Hard gates (before reporting)

Complete in order for each finding you intend to report. Do not advance until the pass condition is satisfied.

1. Location artifact — The finding includes [FILE:LINE] (or a line range) copied from the current file contents; the path resolves in this repo. 2. Scope read — You read the full surrounding unit: the type or function that owns the CloudKit work (for example the CKOperation subclass usage, completion handler chain, or CKRecord lifecycle), not only a diff hunk or isolated snippet. 3. CloudKit or deployment claim (only if the finding depends on container identifiers, public vs private database choice, custom zone requirement, iCloud account state, entitlements, or production schema) — You name one concrete artifact you inspected (for example com.apple.developer.icloud-container-environment or container ID in the entitlements file, CKContainer.default() vs custom identifier in source, Info.plist / target capability, or evidence that schema is deployed) or you downgrade the item to an open question in Review Questions. 4. Protocol — Pre-report steps in review-verification-protocol are satisfied for this item (no finding if they are not).

Use the issue format [FILE:LINE] ISSUE_TITLE for each reported finding. Hard gate 4 is the full pre-report checklist for this skill’s review type.

CloudKit Container Setup

Container Architecture

// Default container (matches app's bundle identifier)
let container = CKContainer.default()

// Custom container (explicit identifier - recommended)
let container = CKContainer(identifier: "iCloud.com.company.appname")

Container identifiers cannot be deleted once created - verify naming before creation.

Database Types

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

Custom Zones

Custom zones provide atomic operations, sharing, and change tokens. Required for production apps.

let zoneID = CKRecordZone.ID(zoneName: "MyZone", ownerName: CKCurrentUserDefaultName)
let zone = CKRecordZone(zoneID: zoneID)

let operation = CKModifyRecordZonesOperation(recordZonesToSave: [zone], recordZoneIDsToDelete: nil)
privateDB.add(operation)

Critical Anti-Patterns

1. Using Default Zone for Production

// BAD: Default zone lacks atomic operations and sharing
let record = CKRecord(recordType: "Note")
privateDB.save(record) { _, _ in }

// GOOD: Use custom zone
let zoneID = CKRecordZone.ID(zoneName: "NotesZone", ownerName: CKCurrentUserDefaultName)
let recordID = CKRecord.ID(recordName: UUID().uuidString, zoneID: zoneID)
let record = CKRecord(recordType: "Note", recordID: recordID)

2. Missing Account Status Check

// BAD: Assumes iCloud is available
func saveUserData() {
    container.privateCloudDatabase.save(record) { _, _ in }
}

// GOOD: Check account status first
container.accountStatus { status, error in
    guard status == .available else {
        // Handle: .noAccount, .restricted, .couldNotDetermine
        return
    }
    self.container.privateCloudDatabase.save(record) { _, _ in }
}

3. Not Observing Account Changes

// BAD: Assumes account persists
class DataManager {
    let container = CKContainer.default()
}

// GOOD: Observe account changes
NotificationCenter.default.addObserver(
    forName: .CKAccountChanged,
    object: nil,
    queue: .main
) { _ in
    // Re-check account status, clear private data cache if user changed
}

4. Missing NSPersistentCloudKitContainer Options

// BAD: Missing required options
let container = NSPersistentCloudKitContainer(name: "Model")
container.loadPersistentStores { _, _ in }

// GOOD: Enable required tracking
let description = container.persistentStoreDescriptions.first!
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
description.setOption(true as NSNumber, forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
description.cloudKitContainerOptions = NSPersistentCloudKitContainerOptions(
    containerIdentifier: "iCloud.com.company.app"
)

Required Entitlements

<key>com.apple.developer.icloud-services</key>
<array>
    <string>CloudKit</string>
</array>
<key>com.apple.developer.icloud-container-identifiers</key>
<array>
    <string>iCloud.com.company.appname</string>
</array>

For production:

<key>com.apple.developer.icloud-container-environment</key>
<string>Production</string>

Review Questions

1. Is the container identifier explicitly specified or relying on .default()? 2. Is account status checked before accessing private/shared databases? 3. Are custom zones used for production features? 4. Is CKAccountChanged notification observed? 5. Are entitlements configured for both app and extensions? 6. Is the production environment entitlement set for release builds?

CloudKit Records

CKRecord Basics

Supported field types:

• String, NSNumber, Data, Date, CLLocation
• CKRecord.Reference - links to other records
• CKAsset - binary files (images, audio, documents)
• Arrays of any above type (same-type elements only)

Size limits:

CKRecord.Reference

// Child points to parent with cascade delete
let parentRef = CKRecord.Reference(recordID: parentRecord.recordID, action: .deleteSelf)
childRecord["parentRef"] = parentRef

Actions:

• .deleteSelf - Child deleted when parent deleted
• .none - Child becomes orphan when parent deleted

CKAsset

let fileURL = getLocalFileURL()
let asset = CKAsset(fileURL: fileURL)
record["attachment"] = asset

Assets stored separately, don't count toward 1MB record limit.

Critical Anti-Patterns

1. Storing Child Arrays in Parent

// BAD: Causes conflict resolution nightmares
let parentRecord = CKRecord(recordType: "Album")
parentRecord["photoIDs"] = photoIDs as CKRecordValue

// GOOD: Child references parent
let photoRecord = CKRecord(recordType: "Photo")
let albumRef = CKRecord.Reference(recordID: albumRecord.recordID, action: .deleteSelf)
photoRecord["album"] = albumRef

2. Ignoring Errors

// BAD
database.save(record) { _, error in
    self.updateUI()  // Ignores error!
}

// GOOD
database.save(record) { _, error in
    if let error = error as? CKError {
        switch error.code {
        case .serverRecordChanged:
            self.resolveConflict(error: error)
        case .networkUnavailable, .networkFailure:
            if let retry = error.userInfo[CKErrorRetryAfterKey] as? Double {
                DispatchQueue.main.asyncAfter(deadline: .now() + retry) {
                    self.retrySave(record)
                }
            }
        default:
            self.handleError(error)
        }
        return
    }
    DispatchQueue.main.async { self.updateUI() }
}

3. String Literals for Keys

// BAD: Typos won't be caught
record["titel"] = title

// GOOD: Type-safe keys
enum RecordKeys: String {
    case title, createdAt, category
}
record[RecordKeys.title.rawValue] = title

4. Individual Saves Instead of Batch

// BAD: Separate network call for each record
for record in records {
    database.save(record) { _, _ in }
}

// GOOD: Single batch operation
let operation = CKModifyRecordsOperation(recordsToSave: records, recordIDsToDelete: nil)
operation.modifyRecordsResultBlock = { result in }
database.add(operation)

5. Exceeding Record Size

// BAD: May exceed 1MB limit
record["imageData"] = largeImageData as CKRecordValue

// GOOD: Use CKAsset for binary data
let tempURL = FileManager.default.temporaryDirectory.appendingPathComponent("temp.jpg")
try imageData.write(to: tempURL)
record["image"] = CKAsset(fileURL: tempURL)

6. UI Updates on Background Thread

// BAD: CloudKit callbacks are on background thread
database.fetch(withRecordID: recordID) { record, error in
    self.titleLabel.text = record?["title"] as? String  // Crash!
}

// GOOD
database.fetch(withRecordID: recordID) { record, error in
    DispatchQueue.main.async {
        self.titleLabel.text = record?["title"] as? String
    }
}

7. Downloading All Fields

// BAD: Downloads everything including large assets
let query = CKQuery(recordType: "Photo", predicate: predicate)
database.perform(query, inZoneWith: nil) { records, error in }

// GOOD: Only fetch needed fields
let operation = CKQueryOperation(query: query)
operation.desiredKeys = ["title", "timestamp"]
database.add(operation)

Error Handling Table

Review Questions

1. Are custom record IDs used that match local storage identifiers? 2. Is record data under 1MB with large files as CKAssets? 3. Are relationships using back-references (child->parent) not arrays? 4. Is .deleteSelf used appropriately for cascade delete needs? 5. Are all CloudKit callbacks dispatching UI updates to main thread? 6. Is desiredKeys specified to avoid downloading unnecessary data?

CloudKit Sharing

Sharing Models

Permission Levels

Database Architecture

Private Database (Owner)
└── Custom Zone (required!)
    ├── Root Record
    ├── Child Records (auto-shared)
    └── CKShare Record

Shared Database (Participants)
└── [View into owner's private database]

Critical Anti-Patterns

1. Using Default Zone for Sharing

// BAD: CKShare cannot be saved in Default Zone
let record = CKRecord(recordType: "Item")  // Uses default zone
let share = CKShare(rootRecord: record)
try await privateDatabase.save(share)  // ERROR!

// GOOD: Use custom zone
let zoneID = CKRecordZone.ID(zoneName: "SharedItems", ownerName: CKCurrentUserDefaultName)
let recordID = CKRecord.ID(recordName: UUID().uuidString, zoneID: zoneID)
let record = CKRecord(recordType: "Item", recordID: recordID)
let share = CKShare(rootRecord: record)
try await privateDatabase.modifyRecords(saving: [record, share], deleting: [])

2. Saving CKShare Without Root Record

// BAD: Even if record exists, must save together
let share = CKShare(rootRecord: existingRecord)
try await privateDatabase.save(share)  // ERROR!

// GOOD: Save both together
try await privateDatabase.modifyRecords(saving: [existingRecord, share], deleting: [])

3. Creating New Shares for Already-Shared Records

// BAD: Revokes existing share, removes all participants
func shareContact(_ contact: CKRecord) async throws {
    let share = CKShare(rootRecord: contact)  // Creates NEW share!
    try await privateDatabase.modifyRecords(saving: [contact, share], deleting: [])
}

// GOOD: Check for existing share first
func shareContact(_ contact: CKRecord) async throws -> CKShare {
    if let existingShareRef = contact.share {
        return try await privateDatabase.record(for: existingShareRef.recordID) as! CKShare
    }
    let share = CKShare(rootRecord: contact)
    try await privateDatabase.modifyRecords(saving: [contact, share], deleting: [])
    return share
}

4. Not Verifying Permissions Before Modification

// BAD: Assumes write access
func updateSharedRecord(_ record: CKRecord) async throws {
    record["name"] = "Updated"
    try await sharedDatabase.save(record)  // Fails if readOnly!
}

// GOOD: Check permission first
func canModify(share: CKShare) -> Bool {
    guard let participant = share.currentUserParticipant else { return false }
    return participant.permission == .readWrite || share.owner == participant
}

5. Missing CKSharingSupported in Info.plist

<!-- Required for share acceptance callbacks -->
<key>CKSharingSupported</key>
<true/>

Without this, userDidAcceptCloudKitShareWith is never called.

6. Not Handling Share Acceptance

// BAD: Share links won't work
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    // Missing implementation
}

// GOOD
func windowScene(
    _ windowScene: UIWindowScene,
    userDidAcceptCloudKitShareWith metadata: CKShare.Metadata
) {
    let container = CKContainer(identifier: metadata.containerIdentifier)
    Task {
        do {
            try await container.accept(metadata)
        } catch {
            // Handle error
        }
    }
}

7. Not Setting Share Metadata

// BAD: Email invitations show no context
let share = CKShare(rootRecord: record)

// GOOD: Set title for user-friendly invitations
let share = CKShare(rootRecord: record)
share[CKShare.SystemFieldKey.title] = "Shopping List"
share[CKShare.SystemFieldKey.shareType] = "com.app.shoppinglist"
share[CKShare.SystemFieldKey.thumbnailImageData] = thumbnailData

8. Multiple CKShare per Zone

// BAD: Only ONE CKShare allowed per zone
let share1 = CKShare(recordZoneID: zoneID)
try await privateDatabase.save(share1)
let share2 = CKShare(recordZoneID: zoneID)  // ERROR on save!

// GOOD: Check for existing zone share
func getOrCreateZoneShare(for zoneID: CKRecordZone.ID) async throws -> CKShare {
    let shareID = CKRecord.ID(recordName: CKRecordNameZoneWideShare, zoneID: zoneID)
    do {
        return try await privateDatabase.record(for: shareID) as! CKShare
    } catch {
        let share = CKShare(recordZoneID: zoneID)
        try await privateDatabase.save(share)
        return share
    }
}

UICloudSharingController Integration

func presentShareController(for share: CKShare, record: CKRecord) {
    // Pre-fetch share before presenting
    let controller = UICloudSharingController(share: share, container: container)
    controller.delegate = self
    present(controller, animated: true)
}

// Required delegate methods
extension ViewController: UICloudSharingControllerDelegate {
    func cloudSharingController(_ csc: UICloudSharingController, failedToSaveShareWithError error: Error) {
        // Handle error
    }

    func itemTitle(for csc: UICloudSharingController) -> String? {
        return "Shared Item"
    }
}

Review Questions

1. Is CKShare saved to a custom zone (not Default Zone)? 2. Is root record saved together with CKShare in same operation? 3. Does code check for existing shares before creating new ones? 4. Is CKSharingSupported enabled in Info.plist? 5. Is userDidAcceptCloudKitShareWith implemented? 6. Are shared records accessed from sharedDatabase (not privateDatabase)? 7. Does code verify permissions before attempting modifications? 8. Is share metadata (title, type) set for user-friendly invitations?

CloudKit Subscriptions

Subscription Types

Recommendation: Start with CKDatabaseSubscription unless only using default zone.

Notification Configuration

let info = CKSubscription.NotificationInfo()

// Visible notification
info.alertBody = "New record available"
info.soundName = "default"
info.shouldBadge = true

// Silent notification (background sync)
info.shouldSendContentAvailable = true
// Leave alertBody, soundName, shouldBadge unset

Critical Anti-Patterns

1. Creating Duplicate Subscriptions

// BAD: Creates duplicate on every app launch
func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
    let subscription = CKQuerySubscription(recordType: "Item", predicate: predicate, options: .firesOnRecordCreation)
    database.save(subscription) { _, _ in }
}

// GOOD: Check before creating, use consistent ID
let subscriptionID = "item-creation-subscription"

database.fetch(withSubscriptionID: subscriptionID) { subscription, error in
    if subscription == nil {
        let newSubscription = CKQuerySubscription(
            recordType: "Item",
            predicate: predicate,
            subscriptionID: subscriptionID,
            options: .firesOnRecordCreation
        )
        let info = CKSubscription.NotificationInfo()
        info.shouldSendContentAvailable = true
        newSubscription.notificationInfo = info
        database.save(newSubscription) { _, _ in }
    }
}

2. Missing NotificationInfo

// BAD: Subscription will fail to save
let subscription = CKQuerySubscription(recordType: "Item", predicate: predicate, options: .firesOnRecordCreation)
database.save(subscription) { _, error in }  // Error!

// GOOD: Always configure notificationInfo
let info = CKSubscription.NotificationInfo()
info.shouldSendContentAvailable = true
subscription.notificationInfo = info

3. Wrong Subscription Type for Shared Database

// BAD: CKQuerySubscription doesn't work with shared database
let sharedDB = CKContainer.default().sharedCloudDatabase
let subscription = CKQuerySubscription(recordType: "SharedItem", predicate: predicate, options: .firesOnRecordCreation)
sharedDB.save(subscription) { _, error in }  // Error!

// GOOD: Use CKDatabaseSubscription for shared database
let subscription = CKDatabaseSubscription(subscriptionID: "shared-db-subscription")
let info = CKSubscription.NotificationInfo()
info.shouldSendContentAvailable = true
subscription.notificationInfo = info
sharedDB.save(subscription) { _, _ in }

4. Relying Solely on Push for Sync

// BAD: Only syncing when push arrives
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) {
    syncData()  // Only sync trigger
}

// GOOD: Multiple sync triggers
func applicationDidBecomeActive(_ application: UIApplication) {
    syncData()  // On app launch
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) {
    syncData()  // On notification
}
// Also implement background fetch

5. Not Indexing Predicate Fields

// BAD: Field not indexed in CloudKit Dashboard
let predicate = NSPredicate(format: "category == %@", "news")
// Error: CKError.invalidArguments when saving subscription

// FIX: Enable "Query" indexing for field in CloudKit Dashboard

Registration Flow

// 1. Request authorization
UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
    // 2. Register for remote notifications
    DispatchQueue.main.async {
        UIApplication.shared.registerForRemoteNotifications()
    }
}

// 3. Create subscription after registration
subscriptionManager.ensureSubscriptionExists()

Subscription Manager Pattern

class SubscriptionManager {
    private let subscriptionKey = "cloudkit.subscription.created"

    func ensureSubscriptionExists() {
        guard !UserDefaults.standard.bool(forKey: subscriptionKey) else { return }

        let subscription = CKDatabaseSubscription(subscriptionID: "all-changes")
        let info = CKSubscription.NotificationInfo()
        info.shouldSendContentAvailable = true
        subscription.notificationInfo = info

        let operation = CKModifySubscriptionsOperation(
            subscriptionsToSave: [subscription],
            subscriptionIDsToDelete: nil
        )
        operation.modifySubscriptionsCompletionBlock = { saved, _, error in
            if error == nil {
                UserDefaults.standard.set(true, forKey: self.subscriptionKey)
            }
        }
        database.add(operation)
    }
}

Review Questions

1. Is a specific subscriptionID used to prevent duplicates? 2. Is notificationInfo properly configured before saving? 3. Is the correct subscription type used for the database (shared needs CKDatabaseSubscription)? 4. Are predicate fields indexed in CloudKit Dashboard? 5. Is shouldSendContentAvailable set for silent notifications (without alertBody)? 6. Does the app handle coalesced notifications (not 1:1 with changes)? 7. Is there fallback sync logic for when notifications don't arrive? 8. Is the schema deployed to production before App Store release?