Short answer
There is no supported in-place way to open the same migrated Realm file with a lower schemaVersion without deleting or replacing that file. Restoring a true pre-migration backup can work, but not because Realm downgrades the header in place: the restore replaces the file, so the header comes from the backup. If the backup is a raw Realm file made before migration and is compatible with your SDK, it should open at the old schema version. If the backup is a logical export, it has no Realm header to restore.
What is confirmed vs likely
Confirmed behavior: the schema version is stored in the Realm file, and opening with a lower version than the file records is not a supported rollback path. Realm does not provide a built-in undo-migration API. A successful migration commits.
Likely but SDK-specific: the migration block runs inside a write transaction, so if the block throws, the transaction should roll back and leave the previous schema and data intact. Verify this for your SDK before relying on it. Even if Realm rolls back, external side effects such as files, network calls, or other databases are not rolled back.
Assumption: local Realm file, no sync, same encryption key, and a compatible SDK version. Realm 10.12 is ambiguous across Java, Kotlin, Swift, .NET, and JavaScript, so exact error types and transaction behavior need per-SDK confirmation.
Steps for a real rollback
- Stop the app and close every Realm instance. Do not restore while a process still has the file open.
- Preserve the migrated file for diagnosis. For example:
cp app.realm app.realm.migrated.bak
- Identify whether your backup is a raw Realm file copy or a logical export. This changes the recommendation.
- If it is a raw pre-migration file, restore it to the original path:
cp backup/app.realm app.realm
- Configure
schemaVersion to match the restored file, not to a value lower than that file. If the backup is v1, use 1.
- Open the Realm and verify schema and data. If it fails, check SDK version, encryption key, and sync configuration.
- If you have no raw pre-migration backup, do not lower
schemaVersion. Write a new forward migration at a higher version that transforms data back, or delete the file if the data is disposable.
Backup restore outcomes
| Scenario | Result |
|---|
| Lower schemaVersion on the same migrated file | Not supported; normally errors unless the file is deleted or replaced |
| Raw pre-migration backup restored | Header comes from the backup; opens at old version if SDK and key match |
| Logical export restored | No Realm header; import into a new file at the desired version |
| Reverse migration at a higher version | Supported forward-only path when you must keep the file |
Verification
Test on a copy, never on production data. Create a v1 Realm, write data, open with a v2 migration that throws, then reopen at v1. That tells you whether your SDK rolls back the failed migration. Separately, copy a migrated file and attempt to open it with schemaVersion 1; document the exact error. Also test whether your migration touches external resources, because Realm cannot undo those.
One missing detail that changes the answer
Is your backup a byte-for-byte copy of the .realm file, or an export of records? A raw file can restore the header. An export cannot; you must import it into a new Realm at the schema version you choose.
realm