dpearson2699/swift-ios-skills / skills/cloudkit
cloudkit
VerifiedImplement, 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.7 KB |
| evals/evals.json | config | 3.6 KB |
| references/cloudkit-patterns.md | markdown | 14.6 KB |
references/cloudkit-patterns.md
View on GitHub# CloudKit Patterns
Advanced CloudKit patterns including incremental sync with
CKFetchRecordZoneChangesOperation, sharing with CKShare, record zone
management, CKAsset file storage, batch operations, and CloudKit Dashboard.
## Contents
- [CKFetchRecordZoneChangesOperation (Incremental Sync)](#ckfetchrecordzonechangesoperation-incremental-sync)
- [Server Change Token Management](#server-change-token-management)
- [CKShare and Collaboration](#ckshare-and-collaboration)
- [UICloudSharingController](#uicloudsharingcontroller)
- [Record Zone Management](#record-zone-management)
- [CKAsset File Storage](#ckasset-file-storage)
- [Batch Operations](#batch-operations)
- [Operation Queues and QoS](#operation-queues-and-qos)
- [Encrypted Fields](#encrypted-fields)
- [CloudKit Dashboard](#cloudkit-dashboard)
- [CKFetchDatabaseChangesOperation](#ckfetchdatabasechangesoperation)
## CKFetchRecordZoneChangesOperation (Incremental Sync)
Fetches only records that changed since the last sync. Works with private and
shared databases only. Provide a server change token per zone; use `nil` for
the initial fetch.
```swift
import CloudKit
final class IncrementalSyncManager {
private let database: CKDatabase
private var changeTokens: [CKRecordZone.ID: CKServerChangeToken] = [:]
private let tokenCacheURL: URL
init(database: CKDatabase, cacheDirectory: URL) {
self.database = database
self.tokenCacheURL = cacheDirectory.appendingPathComponent("changeTokens.data")
loadTokens()
}
func fetchChanges(in zoneIDs: [CKRecordZone.ID]) async throws {
var configs: [CKRecordZone.ID: CKFetchRecordZoneChangesOperation.ZoneConfiguration] = [:]
for zoneID in zoneIDs {
let config = CKFetchRecordZoneChangesOperation.ZoneConfiguration()
config.previousServerChangeToken = changeTokens[zoneID]
configs[zoneID] = config
}
let operation = CKFetchRecordZoneChangesOperation(
recordZoneIDs: zoneIDs,
configurationsByRecordZoneID: configs
)
operation.fetchAllChanges = true
// Process changed records
operation.recordWasChangedBlock = { recordID, result in
switch result {
case .success(let record):
self.processChangedRecord(record)
case .failure(let error):
self.handleRecordError(recordID, error: error)
}
}
// Process deleted records
operation.recordWithIDWasDeletedBlock = { recordID, recordType in
self.processDeletedRecord(recordID, type: recordType)
}
// Update change token as zones complete
operation.recordZoneFetchResultBlock = { zoneID, result in
switch result {
case .success(let (serverChangeToken, _, _)):
self.changeTokens[zoneID] = serverChangeToken
self.saveTokens()
case .failure(let error):
if let ckError = error as? CKError,
ckError.code == .changeTokenExpired {
// Clear token and refetch from scratch
self.changeTokens[zoneID] = nil
self.saveTokens()
}
}
}
operation.fetchRecordZoneChangesResultBlock = { result in
if case .failure(let error) = result {
print("Fetch zone changes failed: \(error)")
}
}
operation.qualityOfService = .utility
database.add(operation)
}
// MARK: - Token Persistence
private func loadTokens() {
guard let data = try? Data(contentsOf: tokenCacheURL),
let tokens = try? NSKeyedUnarchiver.unarchivedObject(
ofClasses: [NSDictionary.self, CKRecordZone.ID.self,
CKServerChangeToken.self],
from: data) as? [CKRecordZone.ID: CKServerChangeToken]
else { return }
changeTokens = tokens
}
private func saveTokens() {
guard let data = try? NSKeyedArchiver.archivedData(
withRootObject: changeTokens, requiringSecureCoding: true)
else { return }
try? data.write(to: tokenCacheURL)
}
}
```
## Server Change Token Management
Change tokens are opaque pointers to a point in a zone's change history. Rules:
- Tokens conform to `NSSecureCoding` -- safe to persist to disk.
- Zone change tokens are NOT interchangeable with database change tokens.
- A `.changeTokenExpired` error means the token is too old; reset to `nil` and
refetch all changes.
- On `recordZoneFetchResultBlock`, cache the returned token immediately.
```swift
// Persist token alongside zone ID
func cacheToken(_ token: CKServerChangeToken?, for zoneID: CKRecordZone.ID) {
guard let token else {
UserDefaults.standard.removeObject(forKey: "token-\(zoneID.zoneName)")
return
}
let data = try? NSKeyedArchiver.archivedData(
withRootObject: token, requiringSecureCoding: true)
UserDefaults.standard.set(data, forKey: "token-\(zoneID.zoneName)")
}
func cachedToken(for zoneID: CKRecordZone.ID) -> CKServerChangeToken? {
guard let data = UserDefaults.standard.data(forKey: "token-\(zoneID.zoneName)")
else { return nil }
return try? NSKeyedUnarchiver.unarchivedObject(
ofClass: CKServerChangeToken.self, from: data)
}
```
## CKShare and Collaboration
CKShare manages shared access to records or entire record zones. Limit: 100
participants per share. Available iOS 10+.
### Hierarchy-Based Sharing
Share a root record and its children (linked via `parent` references).
```swift
import CloudKit
// Create a share for a root record
let rootRecord = CKRecord(recordType: "Album", recordID: albumRecordID)
let share = CKShare(rootRecord: rootRecord)
share.publicPermission = .readOnly
// Customize share appearance
share[CKShare.SystemFieldKey.title] = "Vacation Photos" as CKRecordValue
share[CKShare.SystemFieldKey.shareType] = "com.example.album" as CKRecordValue
// Save share and root record together
let operation = CKModifyRecordsOperation(
recordsToSave: [rootRecord, share],
recordIDsToDelete: nil
)
operation.modifyRecordsResultBlock = { result in
switch result {
case .success:
print("Share URL: \(share.url?.absoluteString ?? "nil")")
case .failure(let error):
print("Sharing failed: \(error)")
}
}
privateDB.add(operation)
```
### Zone-Wide Sharing
Share all records in a custom zone.
```swift
let zoneID = CKRecordZone.ID(zoneName: "SharedAlbums")
let share = CKShare(recordZoneID: zoneID)
share.publicPermission = .readWrite
```
### Adding Participants
```swift
// Look up participants by email
let lookupInfo = CKUserIdentity.LookupInfo(emailAddress: "friend@example.com")
let participants = try await container.shareParticipants(
forEmailAddresses: ["friend@example.com"])
for participant in participants {
participant.permission = .readWrite
share.addParticipant(participant)
}
// Save the updated share
try await privateDB.save(share)
```
### Accepting a Share
```swift
// In AppDelegate or SceneDelegate
func userDidAcceptCloudKitShare(with metadata: CKShare.Metadata) {
let container = CKContainer(identifier: metadata.containerIdentifier)
Task {
do {
try await container.accept([metadata])
// Fetch shared records from container.sharedCloudDatabase
} catch {
print("Accept failed: \(error)")
}
}
}
```
**Required**: add `CKSharingSupported = YES` to Info.plist so the system can
launch your app from share URLs.
## UICloudSharingController
Present the system sharing UI (iOS only).
```swift
import UIKit
import CloudKit
func presentSharingUI(for share: CKShare, container: CKContainer,
from viewController: UIViewController) {
let sharingController = UICloudSharingController(share: share, container: container)
sharingController.delegate = self
sharingController.availablePermissions = [.allowReadOnly, .allowReadWrite, .allowPrivate]
viewController.present(sharingController, animated: true)
}
// UICloudSharingControllerDelegate
extension MyClass: UICloudSharingControllerDelegate {
func cloudSharingController(
_ csc: UICloudSharingController,
failedToSaveShareWithError error: Error
) {
print("Save share error: \(error)")
}
func itemTitle(for csc: UICloudSharingController) -> String? {
return "My Shared Album"
}
}
```
## Record Zone Management
Custom record zones in the private database enable atomic commits, change
tracking with tokens, and record sharing.
```swift
// Create
let zoneID = CKRecordZone.ID(zoneName: "NotesZone", ownerName: CKCurrentUserDefaultName)
let zone = CKRecordZone(zoneID: zoneID)
try await privateDB.save(zone)
// Fetch all zones
let zones = try await privateDB.allRecordZones()
// Delete
try await privateDB.deleteRecordZone(withID: zoneID)
```
**Note**: the default zone does not support custom change tokens or atomic
operations. Always use custom zones for sync.
## CKAsset File Storage
Use CKAsset for files, images, and binary data larger than a few KB. Assets do
not count toward the 1 MB record limit.
```swift
// Save an image as a CKAsset
let tempURL = FileManager.default.temporaryDirectory.appendingPathComponent("photo.jpg")
try imageData.write(to: tempURL)
let record = CKRecord(recordType: "Photo")
record["image"] = CKAsset(fileURL: tempURL)
record["caption"] = "Sunset at the beach" as CKRecordValue
try await privateDB.save(record)
// Fetch and read the asset
let fetched = try await privateDB.record(for: record.recordID)
if let asset = fetched["image"] as? CKAsset,
let fileURL = asset.fileURL {
let data = try Data(contentsOf: fileURL)
// Move to app container immediately -- staging area is temporary
let permanentURL = documentsDir.appendingPathComponent("photo.jpg")
try FileManager.default.moveItem(at: fileURL, to: permanentURL)
}
// Remove an asset (orphan it)
record["image"] = nil
try await privateDB.save(record)
// CloudKit periodically deletes orphaned assets from the server
```
**Exclude assets from fetch when not needed** using `desiredKeys` on operations
to save bandwidth.
## Batch Operations
Use `CKModifyRecordsOperation` for atomic saves and deletes.
```swift
let recordsToSave: [CKRecord] = [record1, record2, record3]
let idsToDelete: [CKRecord.ID] = [oldRecordID]
let operation = CKModifyRecordsOperation(
recordsToSave: recordsToSave,
recordIDsToDelete: idsToDelete
)
operation.savePolicy = .changedKeys // Only upload modified fields
operation.isAtomic = true // All or nothing (custom zones only)
operation.perRecordSaveBlock = { recordID, result in
switch result {
case .success(let record): print("Saved: \(recordID)")
case .failure(let error): print("Failed: \(recordID) \(error)")
}
}
operation.perRecordDeleteBlock = { recordID, result in
switch result {
case .success: print("Deleted: \(recordID)")
case .failure(let error): print("Delete failed: \(recordID) \(error)")
}
}
operation.modifyRecordsResultBlock = { result in
if case .failure(let error) = result {
print("Batch failed: \(error)")
}
}
// CloudKit limits: 400 records per operation
operation.qualityOfService = .userInitiated
privateDB.add(operation)
```
**Max 400 records per operation.** For larger batches, split into chunks.
## Operation Queues and QoS
Set appropriate quality of service:
| Scenario | QoS |
|----------|-----|
| User triggered action | `.userInitiated` |
| Background sync | `.utility` |
| Pre-fetch / maintenance | `.background` |
```swift
// Use operation groups for related operations
let group = CKOperationGroup()
group.expectedSendSize = .kilobytes
group.expectedReceiveSize = .megabytes
let config = CKOperation.Configuration()
config.qualityOfService = .utility
config.group = group
let operation = CKQueryOperation(query: query)
operation.configuration = config
database.add(operation)
```
## Encrypted Fields
Use `encryptedValues` (iOS 15+) for sensitive private or shared data that does
not need query or sort indexes. CloudKit can encrypt only new schema fields;
you cannot convert an existing field to encrypted storage, and encrypted values
are unavailable for public database records. `CKAsset` data is encrypted by
default, while `CKRecord.Reference` is not encrypted because CloudKit needs it
for server-side relationship handling.
```swift
let record = CKRecord(recordType: "HealthEntry")
record.encryptedValues["heartRate"] = 72 as CKRecordValue
record.encryptedValues["notes"] = "Resting" as CKRecordValue
// Non-sensitive fields remain in plain text
record["date"] = Date() as CKRecordValue
try await privateDB.save(record)
// Read encrypted values
let fetched = try await privateDB.record(for: record.recordID)
let heartRate = fetched.encryptedValues["heartRate"] as? Int
```
## CloudKit Dashboard
Access at [iCloud Dashboard](https://icloud.developer.apple.com/dashboard).
Key capabilities:
- **Schema**: view/edit record types, fields, indexes. Add indexes only for
queried fields in production.
- **Records**: browse, create, edit, delete records in any database.
- **Subscriptions**: view active subscriptions.
- **Logs**: monitor API calls, errors, and latency.
- **Telemetry**: track request counts, error rates, latency percentiles.
- **Environment toggle**: switch between Development and Production. Simulator
only works with Development.
- **Deploy to Production**: migrate schema changes from dev to prod. Production
does not allow adding new record types or fields programmatically.
## CKFetchDatabaseChangesOperation
Discover which zones changed in a database. Use with shared database where you
do not know zone IDs in advance.
```swift
var dbChangeToken: CKServerChangeToken? = loadDatabaseChangeToken()
let operation = CKFetchDatabaseChangesOperation(
previousServerChangeToken: dbChangeToken
)
operation.fetchAllChanges = true
var changedZoneIDs: [CKRecordZone.ID] = []
var deletedZoneIDs: [CKRecordZone.ID] = []
operation.recordZoneWithIDChangedBlock = { zoneID in
changedZoneIDs.append(zoneID)
}
operation.recordZoneWithIDWasDeletedBlock = { zoneID in
deletedZoneIDs.append(zoneID)
}
operation.fetchDatabaseChangesResultBlock = { result in
switch result {
case .success(let (token, _)):
dbChangeToken = token
saveDatabaseChangeToken(token)
// Now fetch zone changes for changedZoneIDs
case .failure(let error):
if let ckError = error as? CKError,
ckError.code == .changeTokenExpired {
dbChangeToken = nil
// Refetch from scratch
}
}
}
operation.qualityOfService = .utility
sharedDB.add(operation)
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |