MigrationException during schema migration leaves Realm file state ambiguous
0 reputation · 25 Aug 2025, 05:36 UTC
When a migration block throws an exception, Realm throws a MigrationException (or RealmMigrationNeededException in older versions) and refuses to open the Realm file. The documented recovery paths are implementing a correct migration block or enabling deleteRealmIfMigrationNeeded=true to wipe the database. However, the documentation does not explicitly guarantee atomicity of the migration process.
The precise goal is to determine whether a migration that crashes mid-way—after modifying some objects but before completing—can leave the on-disk file in a corrupted state that deleteRealmIfMigrationNeeded cannot cleanly handle. This matters for production apps where a buggy migration release could leave users with an unopenable Realm that also resists the standard wipe-and-reopen recovery.
Constraints include the lack of transactional rollback for migrations, the requirement to delete all auxiliary files (.realm.lock, .realm.note) for manual recovery, and the additional encryption key requirement for encrypted Realms.
- Does Realm provide any atomicity guarantee for the migration process, or can a partial migration leave the file in a state that requires manual file deletion beyond
deleteRealmIfMigrationNeeded? - If corruption is possible, what is the minimal set of files that must be removed to guarantee a clean reopen with the new schema?