Realm Migration
Parent: MongoDB Atlas Device SDK · Published reference · snapshot 2026-10-24 · skill mongodb-cohort-0ecd8d6fb6f0
↓ Facts as markdownall context files
Source-anchored research for Realm Migration. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Definitions
- Replacing Realm is an application migration as well as a data import. PowerSync’s production case changes the local database to SQLite; RxDB’s guide changes schema representation, queries, subscriptions and write APIs. Neither path is a drop-in Realm SDK substitution. (high confidence) [source]
How it works
- Local Realm schema upgrades use a schema version and migration code to reconcile an existing file with the new application schema; the Java API requires a migration when the version increases, and .NET exposes old and new database views for transformations. (high confidence) [source]
- In issue #8656, a developer reported a schema version unexpectedly reading as zero and a rename failing because the old property did not exist. A maintainer could not reproduce version loss through writeCopy; the report alone does not establish a general writeCopy defect. (low confidence) [source]
- Matching property names across old and current schemas do not prove semantic compatibility: the archived Swift guide warns that deleting and later reintroducing a property can leave stale values when intermediate releases are skipped. (low confidence) [source]
- Historical synchronized Realms did not use the local schemaVersion/migrationBlock mechanism. In June 2023, Realm maintainer Thomas Goyne explained that adding a required server field without backfilling existing documents can make those documents unsyncable and remove corresponding client objects. (low confidence) [source]
- The June 2023 maintainer guidance recommends backfilling a new required field before deploying the server schema and accounting for concurrent document creation; terminating and restarting sync is unnecessary for adding properties and can cause client resets. This is historical guidance, not a currently verified service procedure. (low confidence) [source]
How-to and procedures
- Use the migration rename API to preserve existing values when a persisted property changes name; Swift renameProperty and .NET RenameProperty support this operation without an application-level value copy. (high confidence) [source]
Comparisons and alternatives
- RxDB recommends checkpointed batch imports with idempotent bulkUpsert so interrupted imports can resume. For React Native, the guide says to store the checkpoint in the RxDB database as a local document rather than browser localStorage. (low confidence) [source]
- Realm Java deleteRealmIfMigrationNeeded explicitly warns that it loses data. Treat deleting the database to clear a migration error as destructive recovery rather than a data-preserving upgrade. (low confidence) [source]
- RxDB’s guide explicitly says it has no cross-document transactions and uses field-level encryption. A Realm-to-RxDB migration therefore needs a transaction and encryption review rather than assuming parity with Realm write transactions and whole-file encryption. (low confidence) [source]
Facts and statements
- The .NET Migration API can read removed properties dynamically from OldRealm, update corresponding objects in NewRealm, and preserve values through RenameProperty. RemoveType removes the type and its stored data. (low confidence) [source]
- Test upgrades from every supported persisted schema directly to the latest schema, including skipped app releases. Realm’s example checks v0, v1, v2, v3 and v4 against v5; its archived Swift guide uses independent oldSchemaVersion threshold checks. (high confidence) [source]
- In Realm Swift issue #8105, a widget migrated a shared Realm without an app-only model, leaving the new version number with that model's old schema. Maintainers require the app and extension to open the Realm with matching configurations, including schemas. (low confidence) [source]
- Preserve device-local data during a backend migration. Steve Nosse used a client-side Realm-to-SQLite copy alongside a remote collection migration; RxDB likewise imports the local Realm file so previously unsynchronized records can enter the replacement system. (high confidence) [source]
- In Steve Nosse's migration, changing authentication providers required mapping user IDs while preserving data ownership. A forced app upgrade stopped users from continuing to save into the legacy system. These are reported cutover choices, not universal requirements. (low confidence) [source]
- Local Realm migrations can explicitly transform data: archived Swift documentation exposes schemaVersion and migrationBlock, while the .NET API exposes SchemaVersion and MigrationCallback with access to the old and new Realms. (high confidence) [source]
- Validate transformed data during a staged rollout. Facilitron reports migrating screen by screen with two app versions and side-by-side audits; RxDB’s guide describes a transition release followed by a separate cleanup release. (medium confidence) [source]
- RxDB’s migration guide recommends importing existing local Realm data in batches, persisting progress and using idempotent upserts so an interrupted import can resume. It also warns that unsynchronized data may exist only in the device Realm file. (low confidence) [source]
- Preserve upgrade support for late updaters: RxDB’s guide says devices that skip the transition release must still be able to export their Realm file, and Realm’s own example verifies migration paths from multiple older versions. Removing conversion code requires an explicit supported-version policy. (medium confidence) [source]
- In PowerSync’s November 18, 2025 Facilitron case study, the app retained MongoDB Atlas backend databases while replacing client Realm storage with SQLite and introducing PowerSync plus a custom backend API. This is a reported architecture, not evidence that all Realm migrations can retain their backend unchanged. (low confidence) [source]
Children
- Realm schema upgrade testing (frontier)
- Resumable device data import (frontier)
- Migration identity mapping (frontier)
- Cross-target Realm migration safety (frontier)
Frontier under this node: Cross-target Realm migration safety, Migration identity mapping, Realm schema upgrade testing, Resumable device data import