SwiftData 迁移诊断与修复指南：解决崩溃、数据丢失和关系损坏

axiom-swiftdata-migration-diag by charleswiltgen/axiom

152 周安装量

715 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/charleswiltgen/axiom --skill axiom-swiftdata-migration-diag

iOS 数据库 Swift

🇨🇳中文介绍

SwiftData 迁移诊断

概述

SwiftData 迁移失败表现为生产环境崩溃、数据丢失、关系损坏或仅在模拟器中成功。核心原则 90% 的迁移失败源于 VersionedSchema 中缺少模型、关系反向声明问题或未经测试的迁移路径——而非 SwiftData 框架本身的错误。

危险信号 — 怀疑 SwiftData 迁移问题

如果出现以下任何情况，请怀疑迁移配置问题：

更改架构后应用启动时崩溃
"Expected only Arrays for Relationships" 错误
"The model used to open the store is incompatible with the one used to create the store"
"Failed to fulfill faulting for [relationship]"
迁移在模拟器中有效，但在真实设备上崩溃
迁移前存在的数据在迁移后消失
迁移后关系损坏（不应为 nil 的地方出现 nil）
❌ 禁止 "SwiftData migrations are broken, we should use Core Data"
- SwiftData 在生产应用中处理了数百万次迁移
- 架构不匹配和关系错误始终是配置问题，而非框架问题
- 不要合理化问题——诊断它

关键区别 模拟器在每次重建时都会删除数据库，从而隐藏了架构不匹配问题。真实设备保留持久化数据库，并在架构不匹配时立即崩溃。强制要求：在发布前，使用真实数据在真实设备上测试迁移。

强制性的第一步

始终首先运行这些步骤（在更改代码之前）：

// 1. 识别崩溃/问题类型
// 截图崩溃信息并记录：
//   - "Expected only Arrays" = 关系反向声明缺失
//   - "incompatible model" = 架构版本不匹配
//   - "Failed to fulfill faulting" = 关系完整性损坏
//   - 模拟器有效，设备崩溃 = 未经测试的迁移路径
// 记录："Error type: [exact message]"

// 2. 检查架构版本配置
// 在迁移计划中：
enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        // ✅ 验证：所有版本是否按顺序排列？
        // ✅ 验证：最新版本是否与容器匹配？
        [SchemaV1.self, SchemaV2.self, SchemaV3.self]
    }

    static var stages: [MigrationStage] {
        // ✅ 验证：迁移阶段是否与架构转换匹配？
        [migrateV1toV2, migrateV2toV3]
    }
}

// 在应用中：
let schema = Schema(versionedSchema: SchemaV3.self)  // ✅ 验证：是否与计划中的最新版本匹配？
let container = try ModelContainer(
    for: schema,
    migrationPlan: MigrationPlan.self  // ✅ 验证：计划是否已注册？
)
// 记录："Schema version: latest is [version]"

// 3. 检查所有模型是否包含在 VersionedSchema 中
enum SchemaV2: VersionedSchema {
    static var models: [any PersistentModel.Type] {
        // ✅ 验证：是否列出了所有模型？（即使是未更改的模型）
        [Note.self, Folder.self, Tag.self]
    }
}
// 记录："Missing models? Yes/no"

// 4. 检查关系反向声明
@Model
final class Note {
    @Relationship(deleteRule: .nullify, inverse: \Folder.notes)  // ✅ 验证：是否指定了反向关系？
    var folder: Folder?

    @Relationship(deleteRule: .nullify, inverse: \Tag.notes)  // ✅ 验证：是否指定了反向关系？
    var tags: [Tag] = []
}
// 记录："Relationship inverses: all specified? Yes/no"

// 5. 启用 SwiftData 调试日志
// 在 Xcode scheme 中，添加参数：
// -com.apple.coredata.swiftdata.debug 1
// 运行并检查控制台中的 SQL 查询
// 记录："Debug log shows: [what you see]"

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

验证迁移成功完成

当迁移看似完成且没有错误，但你想验证数据完整性时，请使用此部分。

迁移运行且未崩溃后：

// 1. 验证记录数量与迁移前匹配
let context = container.mainContext
let postMigrationCount = try context.fetch(FetchDescriptor<Note>()).count
print("Post-migration count: \(postMigrationCount)")
// 与迁移前数量比较

// 2. 抽查特定记录
let sampleNote = try context.fetch(
    FetchDescriptor<Note>(predicate: #Predicate { $0.id == "known-test-id" })
).first
print("Sample note title: \(sampleNote?.title ?? "MISSING")")

// 3. 验证关系完整
if let note = sampleNote {
    print("Folder relationship: \(note.folder != nil ? "✓" : "✗")")
    print("Tags count: \(note.tags.count)")

    // 验证反向关系
    if let folder = note.folder {
        let folderHasNote = folder.notes.contains { $0.id == note.id }
        print("Inverse relationship: \(folderHasNote ? "✓" : "✗")")
    }
}

// 4. 检查孤立数据
let orphanedNotes = try context.fetch(
    FetchDescriptor<Note>(predicate: #Predicate { $0.folder == nil })
)
print("Orphaned notes (should be 0 if cascade delete worked): \(orphanedNotes.count)")

成功迁移的表现

控制台输出：

Post-migration count: 1523  // 与迁移前匹配
Sample note title: Test Note  // 不是 "MISSING"
Folder relationship: ✓
Tags count: 3
Inverse relationship: ✓
Orphaned notes: 0

如果你看到：

记录数量不同 → 数据丢失（检查 willMigrate 逻辑）
"MISSING" 记录 → 架构不匹配或获取错误
关系为 nil → 反向配置或预取问题
孤立记录 >0 → 级联删除规则未生效

有关具体修复方法，请参见以下模式。

SwiftData migration problem suspected?
├─ Error: "Expected only Arrays for Relationships"?
│  └─ YES → Relationship inverse missing
│     ├─ Many-to-many relationship? → Pattern 1a (explicit inverse)
│     ├─ One-to-many relationship? → Pattern 1b (verify both sides)
│     └─ iOS 17.0 alphabetical bug? → Pattern 1c (default value workaround)
│
├─ Error: "incompatible model" or crash on launch?
│  └─ YES → Schema version mismatch
│     ├─ Latest schema not in plan? → Pattern 2a (add to schemas array)
│     ├─ Migration stage missing? → Pattern 2b (add stage)
│     └─ Container using wrong schema? → Pattern 2c (verify version)
│
├─ Migration runs but data missing?
│  └─ YES → Data loss during migration
│     ├─ Used didMigrate to access old models? → Pattern 3a (use willMigrate)
│     ├─ Forgot to save in willMigrate? → Pattern 3b (add context.save())
│     └─ Custom migration logic wrong? → Pattern 3c (debug transformation)
│
├─ Works in simulator but crashes on device?
│  └─ YES → Untested migration path
│     ├─ Never tested on real device? → Pattern 4a (real device testing)
│     ├─ Never tested upgrade path? → Pattern 4b (test v1 → v2 upgrade)
│     └─ Production data differs from test? → Pattern 4c (test with prod data)
│
└─ Relationships nil after migration?
   └─ YES → Relationship integrity broken
      ├─ Forgot to prefetch relationships? → Pattern 5a (add prefetching)
      ├─ Inverse relationship wrong? → Pattern 5b (fix inverse)
      └─ Delete rule caused cascade? → Pattern 5c (check delete rules)

模式 1a：修复 "Expected only Arrays for Relationships"

原则多对多关系需要显式的反向声明。

❌ 错误（导致 "Expected only Arrays" 错误）

@Model
final class Note {
    var tags: [Tag] = []  // ❌ 缺少反向关系
}

@Model
final class Tag {
    var notes: [Note] = []  // ❌ 缺少反向关系
}

✅ 正确（显式反向关系）

@Model
final class Note {
    @Relationship(deleteRule: .nullify, inverse: \Tag.notes)
    var tags: [Tag] = []  // ✅ 指定了反向关系
}

@Model
final class Tag {
    @Relationship(deleteRule: .nullify, inverse: \Note.tags)
    var notes: [Note] = []  // ✅ 指定了反向关系
}

为什么有效 SwiftData 要求为多对多关系显式指定反向关系，以正确创建连接表。

时间成本 2 分钟添加反向声明

模式 1b：iOS 17.0 字母顺序错误解决方法

原则在 iOS 17.0 中，如果模型名称按字母顺序排列，多对多关系可能会失败。

❌ 错误（在 iOS 17.0 中崩溃）

@Model
final class Actor {
    @Relationship(deleteRule: .nullify, inverse: \Movie.actors)
    var movies: [Movie]  // ❌ 无默认值
}

@Model
final class Movie {
    @Relationship(deleteRule: .nullify, inverse: \Actor.movies)
    var actors: [Actor]  // ❌ 无默认值
}
// 如果 "Actor" < "Movie" 按字母顺序排列，则崩溃

✅ 正确（在 iOS 17.0+ 中有效）

@Model
final class Actor {
    @Relationship(deleteRule: .nullify, inverse: \Movie.actors)
    var movies: [Movie] = []  // ✅ 默认值
}

@Model
final class Movie {
    @Relationship(deleteRule: .nullify, inverse: \Actor.movies)
    var actors: [Actor] = []  // ✅ 默认值
}

修复于 iOS 17.1+

时间成本 1 分钟添加默认值

模式 2a：架构版本不匹配

原则迁移计划的 schemas 数组必须按顺序包含所有版本。

❌ 错误（缺少版本导致崩溃）

enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [SchemaV1.self, SchemaV3.self]  // ❌ 缺少 V2！
    }

    static var stages: [MigrationStage] {
        [migrateV1toV2, migrateV2toV3]  // 引用了 V2 但未包含在 schemas 中
    }
}

✅ 正确（所有版本按顺序排列）

enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [SchemaV1.self, SchemaV2.self, SchemaV3.self]  // ✅ 所有版本
    }

    static var stages: [MigrationStage] {
        [migrateV1toV2, migrateV2toV3]
    }
}

时间成本 2 分钟添加缺失的版本

模式 3a：willMigrate/didMigrate 误用导致的数据丢失

原则旧模型仅在 willMigrate 中可访问，新模型仅在 didMigrate 中可访问。

❌ 错误（尝试在 didMigrate 中访问旧模型）

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: nil,
    didMigrate: { context in
        // ❌ 崩溃：SchemaV1.Note 在此不存在
        let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // 数据丢失，因为转换从未运行
    }
)

✅ 正确（在 willMigrate 中转换）

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        // ✅ SchemaV1.Note 在此存在
        let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // 在旧模型仍可访问时转换数据
        for note in oldNotes {
            note.transformed = transformLogic(note.oldValue)
        }

        try context.save()  // ✅ 在迁移完成前保存
    },
    didMigrate: nil
)

时间成本 5 分钟将逻辑移动到正确的闭包

模式 4a：真实设备测试

原则模拟器在重建时删除数据库。真实设备保留持久化数据库。

# 1. 在真实设备上安装 v1
# 使用 SchemaV1 作为当前版本构建
# 运行应用，创建示例数据（100+ 条记录）

# 2. 验证数据存在
# 检查应用：应看到 100+ 条记录

# 3. 安装带有迁移的 v2
# 使用 SchemaV2 作为当前版本 + 迁移计划构建
# 覆盖现有应用安装（不要删除）

# 4. 验证迁移成功
# 应用启动无崩溃
# 数据仍然存在（100+ 条记录）
# 关系完整

import Testing
import SwiftData

@Test func testMigrationOnRealDevice() throws {
    // 此测试必须在真实设备上运行，而非模拟器
    #if targetEnvironment(simulator)
    throw XCTSkip("Migration test requires real device")
    #endif

    let container = try ModelContainer(
        for: Schema(versionedSchema: SchemaV2.self),
        migrationPlan: MigrationPlan.self
    )

    let context = container.mainContext
    let notes = try context.fetch(FetchDescriptor<SchemaV2.Note>())

    // 验证数据保留
    #expect(notes.count > 0)

    // 验证关系
    for note in notes {
        if note.folder != nil {
            #expect(note.folder?.notes.contains { $0.id == note.id } == true)
        }
    }
}

时间成本 15 分钟在真实设备上测试

模式 5a：关系预取以保持完整性

原则在迁移期间急切获取关系，以避免错误。

❌ 错误（关系可能出错并损坏）

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        let notes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        for note in notes {
            // ❌ 可能触发错误，关系未加载
            let folderName = note.folder?.name
        }
    },
    didMigrate: nil
)

✅ 正确（预取关系）

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        var fetchDesc = FetchDescriptor<SchemaV1.Note>()

        // ✅ 预取关系
        fetchDesc.relationshipKeyPathsForPrefetching = [\.folder, \.tags]

        let notes = try context.fetch(fetchDesc)

        for note in notes {
            // ✅ 关系已加载
            let folderName = note.folder?.name
            let tagCount = note.tags.count
        }

        try context.save()
    },
    didMigrate: nil
)

时间成本 3 分钟添加预取

快速参考：错误 → 修复映射

错误信息	根本原因	修复方法	时间
"Expected only Arrays for Relationships"	多对多反向关系缺失	在两侧添加 `@Relationship(inverse:)`	2 分钟
"The model used to open the store is incompatible"	架构版本不匹配	将缺失的版本添加到 `schemas` 数组	2 分钟
"Failed to fulfill faulting for [relationship]"	关系未预取	添加 `relationshipKeyPathsForPrefetching`	3 分钟
更改架构后应用崩溃	VersionedSchema 中缺少模型	在 `models` 数组中包含所有模型	2 分钟
迁移后数据丢失	转换在错误的闭包中	将逻辑从 didMigrate 移动到 willMigrate	5 分钟
模拟器有效，设备崩溃	未经测试的迁移路径	使用真实数据在真实设备上测试	15 分钟
迁移后关系为 nil	反向关系错误	修复 `@Relationship(inverse:)` 键路径	3 分钟

当迁移失败时，验证所有以下内容：

所有模型都包含在 VersionedSchema.models 数组中
所有架构版本都包含在 SchemaMigrationPlan.schemas 数组中
迁移阶段与架构转换匹配（V1→V2, V2→V3）
多对多关系在两侧都有显式的 inverse:
容器使用正确的最新架构版本初始化
迁移计划在 ModelContainer 初始化中注册
在真实设备上测试（不仅仅是模拟器）
测试升级路径（v1 → v2），不仅仅是全新安装
启用 SwiftData 调试日志（-com.apple.coredata.swiftdata.debug 1）
数据转换逻辑在 willMigrate 中（不在 didMigrate 中）

当你在 30 分钟后仍然卡住

如果你花费了 >30 分钟且迁移问题仍然存在：

停止。你可能是

跳过了强制性的诊断步骤（最常见）
误判了实际问题
为你的症状应用了错误的模式
尚未在真实设备/真实数据上测试
有需要两阶段迁移的复杂边缘情况

声称"技能无效"前的强制性清单

我运行了所有强制性第一步诊断
我识别了问题类型（关系、架构不匹配、数据丢失、测试缺口）
我启用了 SwiftData 调试日志并检查了 SQL 输出
我使用真实数据在真实设备上测试了（不是模拟器）
我应用了决策树中的第一个匹配模式
我验证了所有模型都包含在 VersionedSchema 中
我检查了关系反向声明

如果所有复选框都已勾选但仍然无效

你需要两阶段迁移（在 axiom-swiftdata-migration 技能中涵盖）
时间成本：复杂类型更改迁移需要 30-60 分钟
提问："实际需要什么数据转换？"并实现两阶段模式

时间成本透明度

模式 1（关系反向）：2-3 分钟
模式 2（架构版本）：2-5 分钟
模式 3（willMigrate 修复）：5-10 分钟
模式 4（真实设备测试）：15-30 分钟
模式 5（关系预取）：3-5 分钟

之前 SwiftData 迁移调试每个问题需要 2-8 小时

生产环境中应用启动时崩溃
现有用户数据丢失
迁移后关系损坏
模拟器成功，设备失败
客户信任受损

之后使用系统化诊断需要 15-45 分钟

使用诊断识别问题类型（5 分钟）
应用正确的模式（5-10 分钟）
在真实设备上测试（15-30 分钟）
自信地部署

关键洞察 SwiftData 为每个常见的迁移问题都建立了成熟的模式。问题在于开发者不知道哪种诊断适用于他们的错误。

WWDC : 2025-291, 2023-10195

技能 : axiom-swiftdata-migration, axiom-swiftdata, axiom-database-migration

创建于 2025-12-09 状态生产就绪的诊断模式框架 SwiftData (Apple) Swift 5.9+

🇺🇸English

SwiftData Migration Diagnostics

Overview

SwiftData migration failures manifest as production crashes, data loss, corrupted relationships, or simulator-only success. Core principle 90% of migration failures stem from missing models in VersionedSchema, relationship inverse issues, or untested migration paths—not SwiftData bugs.

Red Flags — Suspect SwiftData Migration Issue

If you see ANY of these, suspect a migration configuration problem:

App crashes on launch after schema change
"Expected only Arrays for Relationships" error
"The model used to open the store is incompatible with the one used to create the store"
"Failed to fulfill faulting for [relationship]"
Migration works in simulator but crashes on real device
Data exists before migration, gone after
Relationships broken after migration (nil where they shouldn't be)
❌ FORBIDDEN "SwiftData migrations are broken, we should use Core Data"
- SwiftData handles millions of migrations in production apps
- Schema mismatches and relationship errors are always configuration, not framework
- Do not rationalize away the issue—diagnose it

Critical distinction Simulator deletes the database on each rebuild, hiding schema mismatch issues. Real devices keep persistent databases and crash immediately on schema mismatch. MANDATORY: Test migrations on real device with real data before shipping.

Mandatory First Steps

ALWAYS run these FIRST (before changing code):

// 1. Identify the crash/issue type
// Screenshot the crash message and note:
//   - "Expected only Arrays" = relationship inverse missing
//   - "incompatible model" = schema version mismatch
//   - "Failed to fulfill faulting" = relationship integrity broken
//   - Simulator works, device crashes = untested migration path
// Record: "Error type: [exact message]"

// 2. Check schema version configuration
// In your migration plan:
enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        // ✅ VERIFY: All versions in order?
        // ✅ VERIFY: Latest version matches container?
        [SchemaV1.self, SchemaV2.self, SchemaV3.self]
    }

    static var stages: [MigrationStage] {
        // ✅ VERIFY: Migration stages match schema transitions?
        [migrateV1toV2, migrateV2toV3]
    }
}

// In your app:
let schema = Schema(versionedSchema: SchemaV3.self)  // ✅ VERIFY: Matches latest in plan?
let container = try ModelContainer(
    for: schema,
    migrationPlan: MigrationPlan.self  // ✅ VERIFY: Plan is registered?
)
// Record: "Schema version: latest is [version]"

// 3. Check all models included in VersionedSchema
enum SchemaV2: VersionedSchema {
    static var models: [any PersistentModel.Type] {
        // ✅ VERIFY: Are ALL models listed? (even unchanged ones)
        [Note.self, Folder.self, Tag.self]
    }
}
// Record: "Missing models? Yes/no"

// 4. Check relationship inverse declarations
@Model
final class Note {
    @Relationship(deleteRule: .nullify, inverse: \Folder.notes)  // ✅ VERIFY: inverse specified?
    var folder: Folder?

    @Relationship(deleteRule: .nullify, inverse: \Tag.notes)  // ✅ VERIFY: inverse specified?
    var tags: [Tag] = []
}
// Record: "Relationship inverses: all specified? Yes/no"

// 5. Enable SwiftData debug logging
// In Xcode scheme, add argument:
// -com.apple.coredata.swiftdata.debug 1
// Run and check Console for SQL queries
// Record: "Debug log shows: [what you see]"

What this tells you

"Expected only Arrays for Relationships" → Proceed to Pattern 1 (relationship inverse fix)
"incompatible model" → Proceed to Pattern 2 (schema version mismatch)
Missing models in VersionedSchema → Proceed to Pattern 3 (complete schema snapshot)
Simulator works, device crashes → Proceed to Pattern 4 (migration testing)
Data lost after migration → Proceed to Pattern 5 (willMigrate/didMigrate misuse)

MANDATORY INTERPRETATION

Before changing ANY code, identify ONE of these:

If error is "Expected only Arrays" AND relationship inverse missing → Relationship configuration issue
If error mentions "incompatible" AND schema versions don't match → Version mismatch
If models are missing from VersionedSchema → Incomplete schema snapshot
If simulator succeeds but device fails → Untested migration path
If data exists before but not after → willMigrate/didMigrate limitation violated

If diagnostics are contradictory or unclear

STOP. Do NOT proceed to patterns yet
Add -com.apple.coredata.swiftdata.debug 1 and examine SQL output
Check file system: does .sqlite file exist? What size?
Establish baseline: what's actually happening vs. what you assumed

Verifying Migration Completed Successfully

Use this section when migration appears to complete without errors, but you want to verify data integrity.

Quick Verification Checklist

After migration runs without crashing:

// 1. Verify record count matches pre-migration
let context = container.mainContext
let postMigrationCount = try context.fetch(FetchDescriptor<Note>()).count
print("Post-migration count: \(postMigrationCount)")
// Compare to pre-migration count

// 2. Spot-check specific records
let sampleNote = try context.fetch(
    FetchDescriptor<Note>(predicate: #Predicate { $0.id == "known-test-id" })
).first
print("Sample note title: \(sampleNote?.title ?? "MISSING")")

// 3. Verify relationships intact
if let note = sampleNote {
    print("Folder relationship: \(note.folder != nil ? "✓" : "✗")")
    print("Tags count: \(note.tags.count)")

    // Verify inverse relationships
    if let folder = note.folder {
        let folderHasNote = folder.notes.contains { $0.id == note.id }
        print("Inverse relationship: \(folderHasNote ? "✓" : "✗")")
    }
}

// 4. Check for orphaned data
let orphanedNotes = try context.fetch(
    FetchDescriptor<Note>(predicate: #Predicate { $0.folder == nil })
)
print("Orphaned notes (should be 0 if cascade delete worked): \(orphanedNotes.count)")

What Successful Migration Looks Like

Console Output:

Post-migration count: 1523  // Matches pre-migration
Sample note title: Test Note  // Not "MISSING"
Folder relationship: ✓
Tags count: 3
Inverse relationship: ✓
Orphaned notes: 0

If you see:

Record count differs → Data loss (check willMigrate logic)
"MISSING" records → Schema mismatch or fetch error
Relationships nil → Inverse configuration or prefetching issue
Orphaned records >0 → Cascade delete rule not working

See patterns below for specific fixes.

Decision Tree

SwiftData migration problem suspected?
├─ Error: "Expected only Arrays for Relationships"?
│  └─ YES → Relationship inverse missing
│     ├─ Many-to-many relationship? → Pattern 1a (explicit inverse)
│     ├─ One-to-many relationship? → Pattern 1b (verify both sides)
│     └─ iOS 17.0 alphabetical bug? → Pattern 1c (default value workaround)
│
├─ Error: "incompatible model" or crash on launch?
│  └─ YES → Schema version mismatch
│     ├─ Latest schema not in plan? → Pattern 2a (add to schemas array)
│     ├─ Migration stage missing? → Pattern 2b (add stage)
│     └─ Container using wrong schema? → Pattern 2c (verify version)
│
├─ Migration runs but data missing?
│  └─ YES → Data loss during migration
│     ├─ Used didMigrate to access old models? → Pattern 3a (use willMigrate)
│     ├─ Forgot to save in willMigrate? → Pattern 3b (add context.save())
│     └─ Custom migration logic wrong? → Pattern 3c (debug transformation)
│
├─ Works in simulator but crashes on device?
│  └─ YES → Untested migration path
│     ├─ Never tested on real device? → Pattern 4a (real device testing)
│     ├─ Never tested upgrade path? → Pattern 4b (test v1 → v2 upgrade)
│     └─ Production data differs from test? → Pattern 4c (test with prod data)
│
└─ Relationships nil after migration?
   └─ YES → Relationship integrity broken
      ├─ Forgot to prefetch relationships? → Pattern 5a (add prefetching)
      ├─ Inverse relationship wrong? → Pattern 5b (fix inverse)
      └─ Delete rule caused cascade? → Pattern 5c (check delete rules)

Common Patterns

Pattern 1a: Fix "Expected only Arrays for Relationships"

PRINCIPLE Many-to-many relationships require explicit inverse declarations.

❌ WRONG (Causes "Expected only Arrays" error)

@Model
final class Note {
    var tags: [Tag] = []  // ❌ Missing inverse
}

@Model
final class Tag {
    var notes: [Note] = []  // ❌ Missing inverse
}

✅ CORRECT (Explicit inverse)

@Model
final class Note {
    @Relationship(deleteRule: .nullify, inverse: \Tag.notes)
    var tags: [Tag] = []  // ✅ Inverse specified
}

@Model
final class Tag {
    @Relationship(deleteRule: .nullify, inverse: \Note.tags)
    var notes: [Note] = []  // ✅ Inverse specified
}

Why this works SwiftData requires explicit inverse for many-to-many to create junction table correctly.

Time cost 2 minutes to add inverse declarations

Pattern 1b: iOS 17.0 Alphabetical Bug Workaround

PRINCIPLE In iOS 17.0, many-to-many relationships could fail if model names were in alphabetical order.

❌ WRONG (Crashes in iOS 17.0)

@Model
final class Actor {
    @Relationship(deleteRule: .nullify, inverse: \Movie.actors)
    var movies: [Movie]  // ❌ No default value
}

@Model
final class Movie {
    @Relationship(deleteRule: .nullify, inverse: \Actor.movies)
    var actors: [Actor]  // ❌ No default value
}
// Crashes if "Actor" < "Movie" alphabetically

✅ CORRECT (Works in iOS 17.0+)

@Model
final class Actor {
    @Relationship(deleteRule: .nullify, inverse: \Movie.actors)
    var movies: [Movie] = []  // ✅ Default value
}

@Model
final class Movie {
    @Relationship(deleteRule: .nullify, inverse: \Actor.movies)
    var actors: [Actor] = []  // ✅ Default value
}

Fixed in iOS 17.1+

Time cost 1 minute to add default values

Pattern 2a: Schema Version Mismatch

PRINCIPLE Migration plan's schemas array must include ALL versions in order.

❌ WRONG (Missing version causes crash)

enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [SchemaV1.self, SchemaV3.self]  // ❌ Missing V2!
    }

    static var stages: [MigrationStage] {
        [migrateV1toV2, migrateV2toV3]  // References V2 but not in schemas
    }
}

✅ CORRECT (All versions in order)

enum MigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [SchemaV1.self, SchemaV2.self, SchemaV3.self]  // ✅ All versions
    }

    static var stages: [MigrationStage] {
        [migrateV1toV2, migrateV2toV3]
    }
}

Time cost 2 minutes to add missing version

Pattern 3a: Data Loss from willMigrate/didMigrate Misuse

PRINCIPLE Old models only accessible in willMigrate, new models only in didMigrate.

❌ WRONG (Tries to access old models in didMigrate)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: nil,
    didMigrate: { context in
        // ❌ CRASH: SchemaV1.Note doesn't exist here
        let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // Data lost because transformation never ran
    }
)

✅ CORRECT (Transform in willMigrate)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        // ✅ SchemaV1.Note exists here
        let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // Transform data while old models still accessible
        for note in oldNotes {
            note.transformed = transformLogic(note.oldValue)
        }

        try context.save()  // ✅ Save before migration completes
    },
    didMigrate: nil
)

Time cost 5 minutes to move logic to correct closure

Pattern 4a: Real Device Testing

PRINCIPLE Simulator deletes database on rebuild. Real devices keep persistent databases.

Testing Workflow

# 1. Install v1 on real device
# Build with SchemaV1 as current version
# Run app, create sample data (100+ records)

# 2. Verify data exists
# Check app: should see 100+ records

# 3. Install v2 with migration
# Build with SchemaV2 as current version + migration plan
# Install over existing app (don't delete)

# 4. Verify migration succeeded
# App launches without crash
# Data still exists (100+ records)
# Relationships intact

Migration Test Code

import Testing
import SwiftData

@Test func testMigrationOnRealDevice() throws {
    // This test MUST run on real device, not simulator
    #if targetEnvironment(simulator)
    throw XCTSkip("Migration test requires real device")
    #endif

    let container = try ModelContainer(
        for: Schema(versionedSchema: SchemaV2.self),
        migrationPlan: MigrationPlan.self
    )

    let context = container.mainContext
    let notes = try context.fetch(FetchDescriptor<SchemaV2.Note>())

    // Verify data preserved
    #expect(notes.count > 0)

    // Verify relationships
    for note in notes {
        if note.folder != nil {
            #expect(note.folder?.notes.contains { $0.id == note.id } == true)
        }
    }
}

Time cost 15 minutes to test on real device

Pattern 5a: Relationship Prefetching to Preserve Integrity

PRINCIPLE Fetch relationships eagerly during migration to avoid faulting errors.

❌ WRONG (Relationships may fault and break)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        let notes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        for note in notes {
            // ❌ May trigger fault, relationship not loaded
            let folderName = note.folder?.name
        }
    },
    didMigrate: nil
)

✅ CORRECT (Prefetch relationships)

static let migrate = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        var fetchDesc = FetchDescriptor<SchemaV1.Note>()

        // ✅ Prefetch relationships
        fetchDesc.relationshipKeyPathsForPrefetching = [\.folder, \.tags]

        let notes = try context.fetch(fetchDesc)

        for note in notes {
            // ✅ Relationships already loaded
            let folderName = note.folder?.name
            let tagCount = note.tags.count
        }

        try context.save()
    },
    didMigrate: nil
)

Time cost 3 minutes to add prefetching

Quick Reference: Error → Fix Mapping

Error Message	Root Cause	Fix	Time
"Expected only Arrays for Relationships"	Many-to-many inverse missing	Add `@Relationship(inverse:)` to both sides	2 min
"The model used to open the store is incompatible"	Schema version mismatch	Add missing version to `schemas` array	2 min
"Failed to fulfill faulting for [relationship]"	Relationship not prefetched	Add `relationshipKeyPathsForPrefetching`	3 min
App crashes after schema change	Missing model in VersionedSchema	Include ALL models in `models` array

Debugging Checklist

When migration fails, verify ALL of these:

All models included in VersionedSchema.models array
All schema versions included in SchemaMigrationPlan.schemas array
Migration stages match schema transitions (V1→V2, V2→V3)
Many-to-many relationships have explicit inverse: on both sides
Container initialized with correct latest schema version
Migration plan registered in ModelContainer initialization
Tested on real device (not just simulator)
Tested upgrade path (v1 → v2), not just fresh install
SwiftData debug logging enabled (-com.apple.coredata.swiftdata.debug 1)
Data transformation logic in willMigrate (not didMigrate)

When You're Stuck After 30 Minutes

If you've spent >30 minutes and the migration issue persists:

STOP. You either

Skipped mandatory diagnostics (most common)
Misidentified the actual problem
Applied wrong pattern for your symptom
Haven't tested on real device/real data
Have complex edge case requiring two-stage migration

MANDATORY checklist before claiming "skill didn't work"

I ran all Mandatory First Steps diagnostics
I identified the problem type (relationship, schema mismatch, data loss, testing gap)
I enabled SwiftData debug logging and examined SQL output
I tested on real device with real data (not simulator)
I applied the FIRST matching pattern from Decision Tree
I verified all models included in VersionedSchema
I checked relationship inverse declarations

If ALL boxes are checked and still broken

You need two-stage migration (covered in axiom-swiftdata-migration skill)
Time cost: 30-60 minutes for complex type change migration
Ask: "What data transformation is actually needed?" and implement two-stage pattern

Time Cost Transparency

Pattern 1 (relationship inverse): 2-3 minutes
Pattern 2 (schema version): 2-5 minutes
Pattern 3 (willMigrate fix): 5-10 minutes
Pattern 4 (real device testing): 15-30 minutes
Pattern 5 (relationship prefetching): 3-5 minutes

Real-World Impact

Before SwiftData migration debugging 2-8 hours per issue

App crashes on launch in production
Data loss for existing users
Relationships broken after migration
Simulator success, device failure
Customer trust damaged

After 15-45 minutes with systematic diagnosis

Identify problem type with diagnostics (5 min)
Apply correct pattern (5-10 min)
Test on real device (15-30 min)
Deploy with confidence

Key insight SwiftData has well-established patterns for every common migration issue. The problem is developers don't know which diagnostic applies to their error.

Resources

WWDC : 2025-291, 2023-10195

Docs : /swiftdata

Skills : axiom-swiftdata-migration, axiom-swiftdata, axiom-database-migration

Created 2025-12-09 Status Production-ready diagnostic patterns Framework SwiftData (Apple) Swift 5.9+

Weekly Installs

Repository

charleswiltgen/axiom

GitHub Stars

606

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode83

claude-code78

codex77

gemini-cli76

cursor76

github-copilot72

SQL查询优化指南：PostgreSQL、Snowflake、BigQuery高性能SQL编写技巧与方言参考

977 周安装