SwiftData migrations are one of those things that feel optional… right until you ship an update and real users upgrade with real data on disk. In this post we’…

Donny Wals's blog offers insights into iOS development, Swift programming, and software engineering best practices. Readers can explore articles covering topics such as SwiftUI, Combine framework, and iOS app architecture patterns. Additionally, they can learn about iOS app testing, debugging techniques, and publishing apps on the App Store.

Donny Wals

SwiftData migrations allow you to evolve your data models safely as your app updates. Start by defining VersionedSchema for each model version, even your initial one. SwiftData handles lightweight migrations automatically for simple changes like adding optional properties, removing fields, or renaming with @Attribute(originalName:). For complex changes requiring new non-optional fields or data transformations, use SchemaMigrationPlan with custom MigrationStage blocks. The willMigrate closure cleans up old data before schema changes, while didMigrate populates new fields afterward. For major restructuring like splitting models, use a bridge version strategy: keep legacy fields temporarily while populating new structures, then remove them in a subsequent version. Always test migrations with real user data across version skips.

A Deep Dive into SwiftData migrations – Donny Wals

Implementing simple versions with VersionedSchema

Performing manual migrations using a migration plan