Realm schema migration: avoid data loss on mobile app updates

Realm database migration: avoid data loss on update

Realm throws Migration is required due to the following errors when the schema doesn't match. If an app with 10,000 users doesn't set up a proper migration, the update will crash every tenth user — and negative App Store reviews are guaranteed. Unlike Room or Core Data, Realm requires explicit specification of the current schema version in the configuration — and if you forget it, the app will crash on the first database access. Our experience shows that a correctly configured migration from the start eliminates downtime and reduces testing time by 30%.

How Realm determines the need for migration?

The schema version is stored inside the .realm file. Realm compares the version in the file with the version specified in RealmConfiguration.schemaVersion. If the versions don't match and migrationBlock is not set — an exception. Developers often forget to increment schemaVersion — this leads to a crash for 90% of users on update. The cost of such a bug is loss of reputation and time for an emergency release.

// iOS — base configuration with migration let config = Realm.Configuration( schemaVersion: 3, migrationBlock: { migration, oldSchemaVersion in if oldSchemaVersion < 2 { // Migration 1 → 2: added category attribute migration.enumerateObjects(ofType: Transaction.className()) { old, new in new?["category"] = "" } } if oldSchemaVersion < 3 { // Migration 2 → 3: rename field migration.renameProperty(onType: Transaction.className(), from: "note", to: "description") } } ) Realm.Configuration.defaultConfiguration = config 

According to the official Realm documentation, all migrations from any older version to the current one are executed in a single migrationBlock — Realm itself determines which version to start from. If you have 5 versions and the user's file is at version 1, Realm will apply all intermediate steps sequentially.

Why is it important to configure schemaVersion correctly?

Every time you change the data model (add, remove, rename fields), you must increment schemaVersion by at least 1. If you don't, Realm will throw an exception when trying to open the database on the user's device. Imagine: you release an update with a new model version but forget to update the schema version — all users (could be a million) won't be able to launch the app. The cost of such a bug is measured not only in fix time but also in reputational loss. We guarantee this won't happen in your project. Savings on support after a proper migration pay for themselves in 2–4 weeks.

What types of operations are supported in migrationBlock?

Adding a field

Realm automatically adds new fields with default values only if the field is optional or has a default in the model. For filling with non-standard values — enumerateObjects. On Android (Realm Kotlin SDK), migration is configured via AutomaticSchemaMigration:

// Android (Realm Kotlin SDK) migration.iterate("Transaction") { oldObject, newObject -> val oldCategory = oldObject.getNullableValue<String>("category") newObject.set("category", oldCategory ?: "uncategorized") } 

Removing a field

Realm simply ignores fields that don't exist in the new model. No explicit migration is required — but you still need to increment schemaVersion. This often causes confusion: developers think removal is safe, but if the version isn't updated, Realm throws an exception.

Renaming a field

migration.renameProperty(onType: "User", from: "fullName", to: "displayName") 

This preserves data. If you delete the old field and add a new one, data is lost. We recommend always using renameProperty to maintain backward compatibility.

Changing a field type

Direct type conversion is not supported — this is a Realm limitation. Approach: read the old value, write to a new field of the new type, then remove the old field from the model (Realm will delete it automatically). For example, if price was a string and becomes a floating-point number:

migration.enumerateObjects(ofType: "Product") { old, new in let priceString = old?["priceString"] as? String ?? "0" new?["price"] = Double(priceString) ?? 0.0 } 

How to debug migration with Realm Studio?

Realm Studio allows you to open a .realm file and view data before and after migration. Useful for verifying correctness. File on Android: /data/data/<package>/files/default.realm (accessible via Device Explorer in Android Studio). Realm Studio processes files 50% faster than direct browser viewing and supports filtering by classes.

How we guarantee correct migration: process and testing

Schema migration is a critical operation. An error leads to data loss, and backup recovery is not always possible. Our engineers have 5+ years of experience with Realm and guarantee correct execution of all transitions.

1. Analyze the current schema and change history.
2. Write migrationBlock for all transformations.
3. Test on Realm Studio and on real backup data.
4. Integrate into the project and deploy via App Store/Google Play.

What's included in the work

We provide:

• Documentation of schema changes with a description of each step.
• Migration code with unit tests and integration tests.
• Rollback instructions for the previous version.
• Support during deployment for 2 weeks.

Migration cost is calculated individually, but often the savings on support pay off within a month. Order Realm migration right now and get a data safety guarantee. Contact us — we will evaluate your project within one business day.

Typical Realm migration mistakes (and how to avoid them)

• Forgetting to increment schemaVersion — the app crashes for all users. Always verify that the version is incremented by at least 1.
• Skipping handling of nullable fields — data turns into nil/null. Use enumerateObjects for explicit assignment.
• Renaming a field by deleting and adding — data loss. Always use renameProperty.
• Using different SDKs in the same project (Java + Kotlin) — library conflict. Choose one SDK and stick with it.

Timelines: from 1 day for simple migrations to 3 days for complex multi-step transitions. We'll evaluate your project for free. Get a Realm migration consultation today — contact us and we'll offer the optimal solution.