axiom-swiftdata-migration

# SwiftData Custom Schema Migrations

## Overview

SwiftData schema migrations move your data safely when models change. **Core principle** SwiftData's `willMigrate` sees only OLD models, `didMigrate` sees only NEW models—you can never access both simultaneously. This limitation shapes all migration strategies.

**Requires** iOS 17+, Swift 5.9+
**Target** iOS 26+ (features like `propertiesToFetch`)

## When Custom Migrations Are Required

### Lightweight Migrations (Automatic)

SwiftData can migrate automatically for:
- ✅ Adding new optional properties
- ✅ Adding new required properties with default values
- ✅ Removing properties
- ✅ Renaming properties (with `@Attribute(originalName:)`)
- ✅ Changing relationship delete rules
- ✅ Adding new models

### Custom Migrations (This Skill)

You need custom migrations for:
- ❌ Changing property types (`String` → `AttributedString`, `Int` → `String`)
- ❌ Making optional properties required (must populate existing nulls)
- ❌ Complex relationship restructuring
- ❌ Data transformations (splitting/merging fields)
- ❌ Deduplication when adding unique constraints

## Example Prompts

These are real questions developers ask that this skill is designed to answer:

#### 1. "I need to change a property from String to AttributedString. How do I migrate existing data with relationships intact?"
→ The skill shows the two-stage migration pattern that works around the willMigrate/didMigrate limitation

#### 2. "My model has a one-to-many relationship with cascade delete. How do I preserve this during a type change migration?"
→ The skill explains relationship prefetching and maintaining inverse relationships across schema versions

#### 3. "I have a many-to-many relationship between Tags and Notes. The migration is failing with 'Expected only Arrays for Relationships'. What's wrong?"
→ The skill covers explicit inverse relationship requirements and iOS 17.0 alphabetical naming bug

#### 4. "I need to rename a model but keep all its relatio