cloudkit

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 8c7069c512a0 · 31 Oct 2026Report an issue or request a re-scan

• Publisherdpearson2699 GitHub userOwner of the repository this skill is read from
• Source folderdpearson2699/swift-ios-skills/skills/cloudkitThe exact folder we audited
• LicenceNOASSERTIONAs the repository states it
• Commit pinned for this verdict8c7069c512a0A new audit runs when the source changes
• Repository statusNot archivedLast push 92 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Implement, 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…

---
name: cloudkit
description: "Implement, 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."
---

# 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

- [Container and Database Setup](#container-and-database-setup)
- [Workflow](#workflow)
- [CKRecord CRUD](#ckrecord-crud)
- [CKQuery](#ckquery)
- [CKSubscription](#cksubscription)
- [CKSyncEngine (iOS 17+)](#cksyncengine-ios-17)
- [SwiftData + CloudKit](#swiftdata--cloudkit)
- [NSUbiquitousKeyValueStore](#nsubiquitouskeyvaluestore)
- [iCloud Drive File Sync](#icloud-drive-file-sync)
- [Account Status and Error Handling](#account-status-and-error-handling)
- [Conflict Resolution](#conflict-resolution)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Workflow

1. Choose the database scope and sync owner; verify capability, container, account status, schema, and environment before writing records.
2. Make a local change durable, enqueue it, then let subscriptions or `CKSyncEngine` drive remote work rather than polling.
3. Persist change tokens or sync-engine state after successful application.
4. Test offline edits, partial failure, rate limiting, token expiry, conflict, account loss, zone deletion, and relaunch.
5. On failure, classify the `CKError`, restore the affected fixture or queue item, apply the documented retry/reset/merge action, and rerun the same scenario. Never restart a full sync blindly after partial success.

Load [references/cloudkit-patterns.md](references/cloudkit-patterns.md) for incremental zone changes, shares, assets, batch operations, and Dashboard procedures.

## 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 |

```swift
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).

```swift
// 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

Apps create custom zones in the private database. Shared databases expose zones
that other users share with the current user. Custom zones support atomic
commits, change tracking, and sharing; public databases do not support custom
zones.

```swift
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:`.

`CONTAINS` tests list membership except for tokenized full-text search with
`self CONTAINS`. `BEGINSWITH` is the string-prefix operator; unsupported
operators, key paths, or field types fail when the query executes.
For every encryption review, explicitly call out field eligibility: encrypted
values cannot be queried or sorted; `CKAsset` is encrypted by default; and
`CKRecord.Reference` cannot be encrypted because CloudKit needs it server-side.

```swift
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/Xcode handles the APNs entitlement when CloudKit is enabled; no
separate explicit App ID push setup is needed. Silent/background processing
still needs Background Modes > Remote notifications.

```swift
// Q

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/dpearson2699/swift-ios-skills
git -C swift-ios-skills checkout 8c7069c512a0

Works in

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 8c7069c512a0

Questions about cloudkit

• github.com/dpearson2699/swift-ios-skills/tree/main/skills/cloudk — the audited source at commit 8c7069c512a0 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology