Automatic vs Manual Schema Migration for Mid-Session Updates

Answer to the Core Questions

Does automatic migration provide sufficient stability for mid‑session updates in small‑scale applications?

Yes, when the schema change is limited to adding new optional fields (or columns with default values) and the app performs only single‑threaded writes. In that scenario, Realm’s automatic migration will perform a lightweight schema check on the next read/write without blocking the main thread, keeping the user session alive and preventing crashes.

When does manual migration outperform automatic migration in preventing runtime crashes during a version transition?

Manual migration is required – and therefore safer – when the change involves:

• Removing or renaming columns
• Changing a field’s type (e.g., Int to String)
• Altering an index or primary key
• Switching encryption keys or using encrypted Realm files
• Running concurrent multi‑threaded writes that could interleave with the migration logic

In these cases, automatic migration will either silently fail or corrupt data, leading to crashes when the app later accesses the altered schema.

Confirmed Facts (from current knowledge)

• Automatic migration works for additive changes only.
• Manual migration is mandatory for destructive or type‑changing changes.
• Small, single‑threaded apps with no encryption can safely enable automatic migration.
• Apps that encrypt Realm files or perform multi‑threaded writes should use manual migration.

Practical Steps for Your Project

1. Identify the change type: list all model changes in the upcoming release.
2. Choose the migration strategy:
   • If all changes are additive (new optional fields with defaults), set setAutomaticMigrationEnabled(true) and bump schemaVersion.
   • Otherwise, implement a RealmMigration class that handles each transformation explicitly.
3. Update the configuration:

   RealmConfiguration config = new RealmConfiguration.Builder(context)
       .schemaVersion(newVersion) // incremented version
       .migration(migrationInstance) // or null if automatic
       .setAutomaticMigrationEnabled(true) // only for additive changes
       .build();
   Realm.setDefaultConfiguration(config);
   

4. Test locally: run the app, perform the update, and verify that no crash occurs during active sessions.
5. Deploy to a staging environment that mirrors production traffic patterns (including any multi‑threaded writes) before rolling out to users.

Diagnostic Detail Needed

Does your application use encrypted Realm files or perform concurrent writes from multiple threads? If so, manual migration is strongly recommended regardless of the change type.