Summary

Migrating a table from non-embedded to embedded is not really easy and obvious in the user-facing SDKs.
This could be improved by automating the main problems and making the migration easier for the user.

Motivation

When migrating a table from non-embedded to embedded users do struggle to get it right because they have to deal with two cases:

• orphaned objects (no backlinks at all) - https://github.com/realm/realm-core/blob/master/src/realm/table.cpp#L1060
• too many backlinks - https://github.com/realm/realm-core/blob/master/src/realm/table.cpp#L1063

The struggle itself has two reasons:

• It's not really all to obvious how to actually handle that during the MigrationBlock (there are multiple questions about how to do that in Cocoa and .NET resulting in https://github.com/realm/realm-dotnet/issues/2408 and https://github.com/realm/realm-cocoa/issues/7145).
• In some cases it simply is not possible at the moment (in .NET we disallow querying EmbeddedObject in general which means they can't even be iterated while in a migration).

While allowing the latter for the special case of migration would partial solve this, I'd like to propose the following changes to solve all those problems at once.

Goals

When applying the post migration changes we ensure the following during https://github.com/realm/realm-core/blob/master/src/realm/object-store/object_store.cpp#L832:

• Objects with too many backlinks get duplicated and assigned one to each backlink so that we automatically end up with objects with only one backlink.
• Orphaned objects will be deleted. This will only happen when a flag is explicitly set to make sure users consciously confirm that data should be deleted.

User-facing API

• Adding a new option deleteOrphanedObjects to the migration, type bool. In the SDKs this would probably make most sense in RealmConfiguration since the MigrationBlock and the DeleteFilesOnMigration flag already live there. In Core this might probably be best situated in ObjectSchema next to IsEmbedded itself.
• Default would be false so that it does not influence any existing migrations.