axiom-data — скилл для Claude Code: работа с данными

---
name: axiom-data
description: Use when working with ANY data persistence, database, storage, CloudKit, migration, or serialization in an Apple app. Covers SwiftData, Core Data, GRDB, SQLite, Realm, CloudKit sync, file storage, Codable, migrations.
license: MIT
---

# Data & Persistence

**You MUST use this skill for ANY data persistence, database, storage, CloudKit, or serialization work.**

<!-- AXIOM_AUDITOR_INLINE_BEGIN — rewritten for Codex by scripts/build-codex.ts; do not hand-edit -->
> **Auditors are skills here.** Where this router says "Launch `some-auditor` agent", invoke the
> matching Codex skill instead — same procedure, no Claude Code agent required.
>
> Available: `axiom-audit-codable`, `axiom-audit-core-data`, `axiom-audit-database-schema`, `axiom-audit-grdb-performance`, `axiom-audit-icloud`, `axiom-audit-storage`, `axiom-audit-swiftdata`.
>
> The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run.
<!-- AXIOM_AUDITOR_INLINE_END -->

## When to Use

Use this skill when working with:
- Databases (SwiftData, Core Data, GRDB, SQLiteData)
- Schema migrations
- CloudKit sync
- File storage (iCloud Drive, local storage)
- Data serialization (Codable, JSON)
- Storage strategy decisions
- Keychain / secure credential storage
- Encryption, signing, key management (CryptoKit)

## Quick Reference

| Symptom / Task | Reference |
|----------------|-----------|
| SwiftData @Model, @Query, ModelContext, sectioned queries / ResultsObserver / @Attribute(.codable) / dynamic compound predicates (`OS27`) | See `skills/swiftdata.md` |
| SwiftData schema migration, VersionedSchema | See `skills/swiftdata-migration.md` |
| SwiftData migration crashes, data loss | See `skills/swiftdata-migration-diag.md` |
| Migrating from Realm to SwiftData | See `skills/realm-migration-ref.md` |
| SwiftData vs SQLiteData decision | See `skills/sqlitedata-migration.md` |
| GRDB queries, upsert, ValueObservation, DatabaseMigrator, encryption | See `skills/grdb.md` |
| GRDB performance, indexes, EXPLAIN QUERY PLAN, cursors, observation not firing | See `skills/grdb-performance.md` |
| Full-text search (FTS5) in GRDB or SQLiteData | See `skills/sqlite-fts-ref.md` |
| Storing or querying JSON inside a SQLite column (JSON1, JSONB) | See `skills/sql-json-ref.md` |
| GRDB shared across app + widget/extension (App Group) | See `skills/grdb-app-groups.md` |
| SQLiteData @Table, CRUD, SyncEngine | See `skills/sqlitedata.md` |
| SQLiteData advanced patterns, CTEs, views | See `skills/sqlitedata-ref.md` |
| `@Shared` / `@SharedReader`, appStorage or fileStorage persistence, custom SharedKey, `isLoading` / `loadError` on `@FetchAll` | See `skills/swift-sharing.md` |
| Core Data stack, relationships, concurrency | See `skills/core-data.md` |
| Core Data migration crashes, thread errors | See `skills/core-data-diag.md` |
| ANY schema migration safety | See `skills/database-migration.md` |
| Codable, JSON encoding/decoding | See `skills/codable.md` |
| Cloud sync architecture, offline-first | See `skills/cloud-sync.md` |
| CloudKit, CKSyncEngine, CKRecord | See `skills/cloudkit-ref.md` |
| iCloud Drive, ubiquitous containers | See `skills/icloud-drive-ref.md` |
| Cloud sync errors, conflict resolution | See `skills/cloud-sync-diag.md` |
| Storage strategy, where to store data | See `skills/storage.md` |
| Storage issues, files disappeared | See `skills/storage-diag.md` |
| Storage management, disk pressure | See `skills/storage-management-ref.md` |
| Keychain / secure credential storage | See axiom-security (skills/keychain.md) |
| Keychain errors (errSecDuplicateItem) | See axiom-security (skills/keychain-diag.md) |
| Keychain API reference | See axiom-security (skills/keychain-ref.md) |
| Encryption / signing / key management | See axiom-security (skills/cryptokit.md) |
| CryptoKit API reference | See axiom-security (skills/cryptokit-ref.md) |
| File protection, NSFileProtection | See axiom-security (skills/file-protection-ref.md) |
| tvOS data persistence (no guaranteed-persistent local storage) | See axiom-swift (skills/tvos.md) |
| tvOS + CloudKit SyncEngine | See `skills/sqlitedata.md` |

### Automated Scanning

**Core Data audit** → `axiom-audit-core-data` (safety violations, architectural gaps — migration options, thread-confinement, N+1 queries, merge policies, context isolation)
**Codable audit** → `axiom-audit-codable` (safety violations, semantic gaps — try? swallowing errors, JSONSerialization, date handling, silent field drops, wrapper-hidden fallbacks, cross-file strategy drift, enum future-case crashes)
**iCloud audit** → `axiom-audit-icloud` (entitlement checks, file coordination, incomplete CKError matrix coverage, missing account-change observation, polling vs CKSubscriptions, SwiftData + CloudKit unsupported features, compound risks like uncoordinated I/O across extensions)
**Storage audit** → `axiom-audit-storage` (wrong file locations, missing backup exclusions, sensitive data on disk vs Keychain, missing App Group containers, unbounded cache growth, orphan files, compound risks like user data in tmp/ + critical content)
**Database schema audit** → `axiom-audit-database-schema` (unsafe ALTER TABLE, DROP operations, missing idempotency, FK constraints declared but not enforced, incomplete upgrade paths, compound risks like INSERT OR REPLACE on FK-referenced tables)
**GRDB performance audit** → `axiom-audit-grdb-performance` (raw SQL string interpolation, missing FK indexes in raw SQL, missing PRAGMA optimize for raw-GRDB apps, journal mode mismatch for app-group DBs, missing observesSuspensionNotifications for shared DBs, prefix-redundant indexes in raw SQL, legacy Record subclass, INSERT OR REPLACE misused as upsert, observation on WITHOUT ROWID tables, WITHOUT ROWID upsert bugs)
**SwiftData audit** → `axiom-audit-swiftdata` (struct models, missing schema registration, array relationships without defaults, background context misuse, N+1 patterns, stale predicates, CloudKit conformance gaps, compound risks like struct model + array relationship)

## Decision Tree

1. SwiftData? → `skills/swiftdata.md`, `skills/swiftdata-migration.md`
2. Core Data? → `skills/core-data.md`, `skills/core-data-diag.md`
3. GRDB? → `skills/grdb.md`
3a. GRDB perf, slow query, schema design for perf? → `skills/grdb-performance.md`
3b. FTS5 (full-text search, any layer)? → `skills/sqlite-fts-ref.md`
3c. DB shared across app + extension/widget/Live Activity? → `skills/grdb-app-groups.md`
4. SQLiteData? → `skills/sqlitedata.md`, `skills/sqlitedata-ref.md`
4a. `@Shared`/`@SharedReader`, or the loading/error state behind `@FetchAll`? → `skills/swift-sharing.md`
5. ANY schema migration? → `skills/database-migration.md` (ALWAYS — prevents data loss)
6. Realm migration? → `skills/realm-migration-ref.md`
7. SwiftData vs SQLiteData? → `skills/sqlitedata-migration.md`
8. Cloud sync architecture? → `skills/cloud-sync.md`
9. CloudKit? → `skills/cloudkit-ref.md`
10. iCloud Drive? → `skills/icloud-drive-ref.md`
11. Cloud sync errors? → `skills/cloud-sync-diag.md`
12. Codable/JSON serialization? → `skills/codable.md`
13. File storage strategy? → `skills/storage.md`, `skills/storage-diag.md`, `skills/storage-management-ref.md`
14. File protection? → See axiom-security (skills/file-protection-ref.md)
15. Keychain / storing tokens, passwords, secrets securely? → See axiom-security (skills/keychain.md), See axiom-security (skills/keychain-diag.md), See axiom-security (skills/keychain-ref.md)
16. SecItem errors (errSecDuplicateItem, errSecItemNotFound, errSecInteractionNotAllowed)? → See axiom-security (skills/keychain-diag.md)
17. Encryption, signing, Secure Enclave, CryptoKit? → See axiom-security (skills/cryptokit.md), See axiom-security (skills/cryptokit-ref.md)
18. Quantum-secure cryptography, HPKE, ML-KEM? → See axiom-security (skills/cryptokit.md)
19. Want Core Data safety scan? → core-data-auditor (Agent)
20. Want Codable anti-pattern scan? → codable-auditor (Agent)
21. Want iCloud sync audit? → icloud-auditor (Agent)
22. Want storage location audit? → storage-auditor (Agent)
23. Want database schema/migration safety scan? → database-schema-auditor (Agent)
23a. Want GRDB performance/app-group scan? → grdb-performance-auditor (Agent)
24. Want SwiftData code audit? → swiftdata-auditor (Agent)
25. tvOS data persistence? → See axiom-swift (skills/tvos.md) (CRITICAL: every local directory is purgeable between launches, so iCloud is the source of truth) + `skills/sqlitedata.md` (CloudKit SyncEngine)
26. SwiftData @MainActor / background context threading? → `/skill axiom-concurrency`
27. Structured data generation with Foundation Models? → `/skill axiom-ai`

#### Sync patterns
- HealthKit anchored/observer queries as a generalizable change-tracking pattern → See axiom-health (skills/sync-and-background.md)

## Anti-Rationalization

| Thought | Reality |
|---------|---------|
| "Just adding a column, no migration needed" | Schema changes without migration crash users. database-migration prevents data loss. |
| "I'll handle the migration manually" | Manual migrations miss edge cases. database-migration has the safe additive patterns and both migration paths to test. |
| "Simple query, I don't need the skill" | Query patterns prevent N+1 and thread-safety issues. The skill has copy-paste solutions. |
| "CloudKit sync is straightforward" | CloudKit has 15+ failure modes. cloud-sync-diag diagnoses them systematically. |
| "I know Codable well enough" | Codable has silent data loss traps (try? swallows errors). codable skill prevents production bugs. |
| "@Shared is just @AppStorage with extra steps" | Mutation goes through `$shared.withLock`; the plain setter is deprecated, and below Sharing 2.8 on Swift 6.3 it is a compile error wherever a SwiftUI binding is chained into shared state. swift-sharing has the migration. |
| "I'll use local storage on tvOS" | No local directory on tvOS is guaranteed to survive between launches — the system purges them, Caches first. See axiom-swift (skills/tvos.md) for the iCloud-first pattern. |
| "UserDefaults is fine for this token" | UserDefaults is unencrypted, backed up to iCloud, and visible to MDM profiles. One audit catches it. keychain stores tokens securely. |
| "I'll encrypt it myself with CommonCrypto" | CryptoKit replaced CommonCrypto's buffer-management nightmares with one-line APIs. cryptokit prevents misuse. |

## Critical Pattern: Migrations

**ALWAYS read `skills/database-migration.md` when adding/modifying database columns.**

This prevents:
- "FOREIGN KEY constraint failed" errors
- "no such column" crashes
- Data loss from unsafe migrations

## Example Invocations

User: "I need to add a column to my SwiftData model"
→ Read: `skills/database-migration.md` (critical - prevents data loss)

User: "How do I query SwiftData with complex filters?"
→ Read: `skills/swiftdata.md`

User: "CloudKit sync isn't working"
→ Read: `skills/cloud-sync-diag.md`

User: "Should I use SwiftData or SQLiteData?"
→ Read: `skills/sqlitedata-migration.md`

User: "How do I persist a setting to UserDefaults and observe it everywhere?"
→ Read: `skills/swift-sharing.md`

User: "Why is my @FetchAll empty — is it loading or did it fail?"
→ Read: `skills/swift-sharing.md`

User: "Check my Core Data code for safety issues"
→ Launch: `core-data-auditor` agent

User: "Scan for Codable anti-patterns before release"
→ Launch: `codable-auditor` agent

User: "Audit my iCloud sync implementation"
→ Launch: `icloud-auditor` agent

User: "Check if my files are stored in the right locations"
→ Launch: `storage-auditor` agent

User: "Audit my database migrations for safety"
→ Launch: `database-schema-auditor` agent

User: "How do I make my GRDB queries faster?"
→ Read: `skills/grdb-performance.md`

User: "Add search to my GRDB-backed app" / "Add search to SQLiteData app"
→ Read: `skills/sqlite-fts-ref.md`

User: "My widget needs to read the same database as the app"
→ Read: `skills/grdb-app-groups.md`

User: "My widget shows stale data from the database"
→ Read: `skills/grdb-app-groups.md`

User: "Audit my GRDB code for performance issues"
→ Launch: `grdb-performance-auditor` agent

User: "Check my SwiftData models for issues"
→ Launch: `swiftdata-auditor` agent

User: "How do I persist data on tvOS?"
→ Invoke: See axiom-swift (skills/tvos.md) + Read: `skills/sqlitedata.md`

User: "My tvOS app loses data between launches"
→ Invoke: See axiom-swift (skills/tvos.md)

User: "How do I store an auth token securely?"
→ Invoke: See axiom-security (skills/keychain.md)

User: "errSecDuplicateItem but I checked and the item doesn't exist"
→ Invoke: See axiom-security (skills/keychain-diag.md)

User: "How do I encrypt data with AES in Swift?"
→ Invoke: See axiom-security (skills/cryptokit.md)

User: "I need to sign data with the Secure Enclave"
→ Invoke: See axiom-security (skills/cryptokit.md)

User: "What's ML-KEM and should I use it?"
→ Invoke: See axiom-security (skills/cryptokit.md)