50 lines
1.7 KiB
Markdown
50 lines
1.7 KiB
Markdown
# CloudKit Schema Guardrails (SwiftData)
|
|
|
|
Use this checklist before changing any `@Model` used by SwiftData + CloudKit.
|
|
|
|
## Why
|
|
|
|
CloudKit-backed SwiftData is additive-first. Breaking schema edits can stop sync or cause migration failures on user devices with existing data.
|
|
|
|
## Safe Changes
|
|
|
|
- Add a new model type.
|
|
- Add a new property that is optional or has a default value.
|
|
- Add a new optional relationship.
|
|
- Add new computed properties (no storage impact).
|
|
- Add new methods/helpers/extensions.
|
|
|
|
## Risky / Avoid Changes
|
|
|
|
- Do not use `@Attribute(.unique)`.
|
|
- Do not remove stored properties that have shipped.
|
|
- Do not rename stored properties that have shipped.
|
|
- Do not change stored property types after shipping.
|
|
- Do not make optional relationships non-optional.
|
|
|
|
## If You Need a Breaking Change
|
|
|
|
1. Add a new property with a new name (keep old property).
|
|
2. Migrate values in app code lazily at runtime.
|
|
3. Ship at least one version with both old+new properties.
|
|
4. Only consider cleanup after all active users have migrated.
|
|
|
|
## Model Rules for This App
|
|
|
|
- Every stored property in `@Model` should be optional or have a default.
|
|
- Relationships must stay optional for CloudKit compatibility.
|
|
- Keep derived state computed (single source of truth).
|
|
|
|
## Pre-merge Checklist
|
|
|
|
- [ ] `xcodebuild ... build` succeeds.
|
|
- [ ] Existing sample/create/edit/delete flows still work.
|
|
- [ ] At least one device signed into iCloud verifies sync behavior.
|
|
- [ ] No schema-breaking edits were introduced.
|
|
|
|
## Operational Notes
|
|
|
|
- First sync on a fresh install can take time.
|
|
- CloudKit conflicts are generally last-writer-wins.
|
|
- Keep mutation methods centralized in state/store types to reduce conflict bugs.
|