Realm Kotlin SDK and Android app releases: making a schema version bump reversible after migration

Short answer

No — copying the .realm file before migration is not a reliable rollback mechanism, and there is no supported downgrade or compatibility mode in current Realm Kotlin SDK 1.x releases. If the file's internal schema version is higher than the configured schemaVersion, opening it is a hard error. The only built-in escape is deleteRealmIfMigrationNeeded(), which destroys local data. Rollback safety has to come from release design, not from file backups.

Why the file-copy approach fails

Two separate problems make pre-migration copies fragile:

• Consistency: a .realm file is memory-mapped with an open write path. Copying it while any Realm instance is open — or while a transaction is in flight — can produce a torn snapshot. compactOnLaunch and background compaction make the timing even less predictable. A consistent copy requires every instance closed and all transactions committed, which is hard to guarantee on an arbitrary launch path.
• It doesn't fix the rollback: even with a perfect backup, the migrated file is still the one on disk. A rolled-back APK opens the default path, sees the higher internal version, and fails. You would need extra restore logic that detects the failure and swaps the backup in — at which point you've built your own downgrade system, with all the data-loss questions that implies (writes made after migration live only in the migrated file).

Version mismatch behavior

Realm stores the schema version in the file header and requires the configured schemaVersion to be greater than or equal to it. A lower configured version is treated as an unhandled migration error in current 1.x releases; there is no documented compatibility mode. The exact exception type and message vary by SDK version, so verify against the version you ship.

Patterns that actually work

1. Keep the schema bump monotonic and additive. Add nullable fields or fields with defaults instead of renaming or removing. Old code ignores columns it doesn't know about at the model level as long as the file version matches — so the key is: don't bump schemaVersion for changes the old build can tolerate. Additive model changes without a version bump keep the file readable by both builds.
2. Gate the bump away from hotfix windows. Treat a schemaVersion increase as a point-of-no-return release: ship it only after staged rollout of the previous version is complete and rollback of that version is no longer offered.
3. Use a versioned file name for breaking changes. A new build opens a new file (e.g., app-v2.realm) and migrates data lazily; the old APK still opens the old file. Rollback then strands nothing, at the cost of dual-file sync/copy logic.

Verification before you rely on this

• Build a test APK at version N, migrate to N+1, reinstall the N APK, and confirm the exact failure mode in your SDK version.
• Test that an additive change with no version bump opens cleanly in both old and new builds.
• If you do keep backups, validate them by closing all instances, copying, and opening the copy in an isolated process.

One detail that changes this recommendation: if your migration is destructive (renames, removals, type changes), additive-compat gating is off the table and the versioned-file pattern becomes the only safe option.