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