Can SwiftData guarantee full rollback after a failed migration step?

Question

Rollback Behavior in SwiftData Migrations
The goal is to preserve data integrity when a schema change fails during a migration. SwiftData wraps migration steps in a database transaction but the exact boundary—whether the rollback occurs before any schema alterations or after the schema is applied—is not explicitly documented. Developers can insert custom MigrationStage implementations to add savepoints and manual control, yet it is unclear how these stages interact with the underlying SQLite transaction.

Constraints include the default SQLite store’s journal mode, potential differences when using in‑memory or CloudKit‑backed stores, and the fact that lightweight migrations hide transaction control from the developer. The unresolved decision is whether a failed migration will always revert the store to its previous version or if partial schema changes might persist.

Questions for clarification:

At what point does SwiftData’s transaction boundary end—before or after schema alterations are committed?
Can a custom MigrationStage reliably enforce a full rollback of both data and schema changes if an error occurs later in the migration plan?
Is the SQLite journal mode sufficient to guarantee atomicity for lightweight migrations that do not expose explicit transaction control?

Tasadduq Burney · Answer

Answer
Yes – for the default SQLite store SwiftData guarantees a full rollback of both data and schema changes when any migration step throws an error.
Why the rollback happens
SwiftData wraps each migration step (including the inferred lightweight‑migration steps) in a single SQLite transaction. If the step throws, the transaction is rolled back, which restores the store to the exact state it had before the migration began.
When the guarantee does not apply

If you manually commit the transaction inside a MigrationStage (e.g., by calling save() or using NSPersistentStoreCoordinator.execute(_:)), the automatic rollback is bypassed and partial changes may persist.
CloudKit‑backed or in‑memory stores use different underlying mechanisms; the SQLite transaction guarantee does not apply, and a failed migration may leave temporary server‑side changes or simply discard the in‑memory copy.
Replacing the default store with a custom NSPersistentStore subclass requires you to verify that it participates in the same transaction semantics.

Verification steps (SQLite store)

Create a SwiftData model with at least two versions; add a migration step that alters a table and then throws an error (e.g., throw MigrationError.failed).
Launch the app with the new model version; let SwiftData run the migration.
After the failure, inspect the store file with the sqlite3 command line: sqlite3 MyStore.sqlite ".schema" and verify that the schema alteration is absent and the data matches the pre‑migration state.
Optionally run PRAGMA journal_mode; to confirm the store is using the default (DELETE) or WAL mode; the rollback works regardless of the mode as long as no commit occurred.

If you are using a CloudKit‑backed or in‑memory store, please confirm the store type so the recommendation can be adjusted.

Can SwiftData guarantee full rollback after a failed migration step?

Rollback Behavior in SwiftData Migrations

1 answer

Answer

Why the rollback happens

When the guarantee does not apply

Verification steps (SQLite store)

Your perspective belongs here.

0 question comments