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 relationships intact."

→ The skill shows @Attribute(originalName:) patterns for lightweight migration

5. "My migration works in the simulator but crashes on a real device with existing data."

→ The skill emphasizes real-device testing and explains why simulator success doesn't guarantee production safety

6. "Why do I have to copy ALL my models into each VersionedSchema, even ones that haven't changed?"

→ The skill explains SwiftData's design: each VersionedSchema is a complete snapshot, not a diff

7. "I'm getting 'The model used to open the store is incompatible with the one used to create the store' error."

→ The skill provides debugging steps for schema version mismatches

8. "How do I test my SwiftData migration before releasing to production?"

→ The skill covers migration testing workflow, real device testing requirements, and validation strategies

---

The willMigrate/didMigrate Limitation

CRITICAL This is the architectural constraint that shapes all SwiftData migration patterns.

What You Can Access

static let migrateV1toV2 = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        // ✅ CAN access: SchemaV1 models (old)
        let v1Notes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // ❌ CANNOT access: SchemaV2 models
        // SchemaV2.Note doesn't exist yet
    },
    didMigrate: { context in
        // ✅ CAN access: SchemaV2 models (new)
        let v2Notes = try context.fetch(FetchDescriptor<SchemaV2.Note>())

        // ❌ CANNOT access: SchemaV1 models
        // SchemaV1.Note is gone
    }
)

Why This Matters

You cannot directly transform data from old type to new type in a single migration stage. Example:

// ❌ IMPOSSIBLE - you can't do this in one stage
willMigrate: { context in
    let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())
    for oldNote in oldNotes {
        let newNote = SchemaV2.Note()  // ❌ Doesn't exist yet!
        newNote.content = oldNote.contentAsAttributedString()
    }
}

Solution Use two-stage migration pattern (covered below).

---

Core Patterns

Pattern 1: Basic VersionedSchema Setup

Every distinct schema version must be defined as a VersionedSchema.

import SwiftData

enum NotesSchemaV1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)

    static var models: [any PersistentModel.Type] {
        [Note.self, Folder.self, Tag.self]  // ALL models, even if unchanged
    }

    @Model
    final class Note {
        @Attribute(.unique) var id: String
        var title: String
        var content: String  // Original type
        var createdAt: Date

        @Relationship(deleteRule: .nullify, inverse: \Folder.notes)
        var folder: Folder?

        @Relationship(deleteRule: .nullify, inverse: \Tag.notes)
        var tags: [Tag] = []

        init(id: String, title: String, content: String, createdAt: Date) {
            self.id = id
            self.title = title
            self.content = content
            self.createdAt = createdAt
        }
    }

    @Model
    final class Folder {
        @Attribute(.unique) var id: String
        var name: String

        @Relationship(deleteRule: .cascade)
        var notes: [Note] = []

        init(id: String, name: String) {
            self.id = id
            self.name = name
        }
    }

    @Model
    final class Tag {
        @Attribute(.unique) var id: String
        var name: String

        @Relationship(deleteRule: .nullify)
        var notes: [Note] = []

        init(id: String, name: String) {
            self.id = id
            self.name = name
        }
    }
}

Key patterns

• Complete snapshot All models included, even unchanged ones
• Semantic versioning Use Schema.Version(major, minor, patch)
• Explicit init SwiftData doesn't synthesize initializers
• Inverse relationships Specify on both sides for bidirectional

---

Pattern 2: Two-Stage Migration for Type Changes

Use when Changing property type (String → AttributedString, Int → String, etc.)

Problem

We want to change Note.content from String to AttributedString, but we can't access both old and new types simultaneously.

Solution

Use an intermediate schema version (V1.1) that has BOTH properties.

// Stage 1: V1 → V1.1 (Add new property alongside old)
enum NotesSchemaV1_1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 1, 0)

    static var models: [any PersistentModel.Type] {
        [Note.self, Folder.self, Tag.self]