When Realm’s Automatic Migration Is Enough – A Practical Guide

Why Automatic Migration Should Be Your First Line of Defense

When you change a data model in a mobile app, the underlying Realm file must match the new schema. Without a migration, the first launch after a change will crash with RealmError: Migration is required. Realm offers two ways to resolve this: the out‑of‑the‑box automatic migration and a hand‑crafted manual migration. The automatic path is fast, requires zero code, and works for most “add or remove a simple field” changes. It is especially handy in early development or when you’re iterating on a feature that won’t touch user‑critical data.

Setting Up Automatic Migration

Automatic migration is enabled by default when you bump the schemaVersion in your RealmConfiguration. The following snippets show how to do this on Android (Kotlin) and iOS (Swift). The key steps are: 1) increase the version number, 2) optionally enable deleteRealmIfMigrationNeeded() for a clean slate, and 3) let Realm handle the rest.

// Android – Kotlin
val config = RealmConfiguration.Builder()
    .schemaVersion(2) // Incremented from 1
    .deleteRealmIfMigrationNeeded() // Optional – only for dev
    .build()
Realm.setDefaultConfiguration(config)

// iOS – Swift
let config = Realm.Configuration(
    schemaVersion: 2, // Incremented
    deleteRealmIfMigrationNeeded: true // Optional
)
Realm.Configuration.defaultConfiguration = config

Remember: deleteRealmIfMigrationNeeded() wipes the entire database on every schema change. It’s a handy shortcut when you’re prototyping, but never ship it to production.

Concrete Example – Adding a New Field

Suppose you have a User object and you want to add an optional nickname field. The steps are:

1. Modify the model class:

   // Kotlin
   open class User : RealmObject() {
       @PrimaryKey var id: String = ""
       var name: String = ""
       var nickname: String? = null // NEW FIELD
   }
   
   // Swift
   class User: Object {
       @Persisted(primaryKey: true) var id: String = ""
       @Persisted var name: String = ""
       @Persisted var nickname: String? = nil // NEW FIELD
   }
   

2. Increment the schema version (see previous section).
3. Run the app. Realm will detect the new field, create the column, and leave existing rows untouched. No manual migration code is needed.

To verify, query a User and check that nickname is nil for pre‑existing rows. Use a breakpoint or log statement to confirm the field exists.

When Automatic Migration Falls Short

Automatic migration only handles structural changes that preserve the underlying data layout. It cannot:

• Rename a field (e.g., firstName to givenName) – Realm will treat this as a new column and drop the old one.
• Split a single field into multiple fields.
• Combine multiple fields into one.
• Transform data values (e.g., converting a string to a date).

In these cases, you must write a manual migration block that explicitly reads, transforms, and writes data. Manual migrations give you full control but add boilerplate and increase the risk of bugs if the logic is incorrect.

Trade‑offs & Practical Checks

Pros of Automatic Migration

• No code – reduces maintenance.
• Zero runtime cost for simple changes.
• Fast startup for small to medium schemas.

Cons

• Data loss risk if you enable deleteRealmIfMigrationNeeded() in production.
• Invisible to developers – you may not realize a migration was performed until a crash occurs.
• No support for complex transformations.

Before shipping, run these sanity checks:

• Profile the app’s startup time after a schema change to ensure migration latency is acceptable.
• Verify that the migrationBlock (if present) is executed by logging a message.
• Test the app on a fresh install and on an upgrade path with existing data.
• Use unit tests that create a Realm in memory, apply a schema change, and assert data integrity.

Actionable Takeaway

For most mobile developers, start with automatic migration:

1. Increment schemaVersion whenever you add or remove a simple field.
2. Keep deleteRealmIfMigrationNeeded() disabled in production.
3. Use manual migrations only when you need to rename, split, or transform data.
4. Always test migration paths, especially after a major schema bump.

By following this approach, you’ll avoid unnecessary boilerplate, keep your codebase clean, and protect user data from accidental loss.