Scheme version/migration configuration clarifications #6821
Conversation
| */ | ||
| @Deprecated |
There was a problem hiding this comment.
Normally this would be correct, but since is this being merged into a branch that will be released as a major (breaking) version. It is fine to just remove this outright. But we do need to add a line about in the CHANGELOG.md Breaking Changes section.
| /** | ||
| * Update the schema version of the Realm and apply the provided migration. | ||
| * <p> | ||
| * The schema version must be equal to or higher than the schema version of the existing |
There was a problem hiding this comment.
What happens if the version is less?
There was a problem hiding this comment.
The conventional IllegalArgumentException with message like Provided schema version 1 is less than last set version 3. I will update the docs.
Don't know if it would make sense to differentiate errors a bit. Also if changing scheme without bumping version number the migration is not triggered and we just emit the usual RealmMigrationNeededException.
realm/realm-library/src/androidTest/kotlin/io/realm/RealmMigrationTestsKotlin.kt
Show resolved
Hide resolved
realm/realm-library/src/androidTest/kotlin/io/realm/RealmMigrationTestsKotlin.kt
Outdated
Show resolved
Hide resolved
realm/realm-library/src/androidTest/kotlin/io/realm/RealmMigrationTestsKotlin.kt
Outdated
Show resolved
Hide resolved
realm/realm-library/src/androidTest/kotlin/io/realm/RealmMigrationTestsKotlin.kt
Outdated
Show resolved
Hide resolved
realm/realm-library/src/androidTest/kotlin/io/realm/RealmMigrationTestsKotlin.kt
Outdated
Show resolved
Hide resolved
realm/realm-library/src/androidTest/kotlin/io/realm/RealmMigrationTestsKotlin.kt
Outdated
Show resolved
Hide resolved
| * @see #schemaVersion(long) | ||
| * @see #migration(RealmMigration) | ||
| */ | ||
| public Builder schemaVersion(long schemaVersion, RealmMigration migration) { |
There was a problem hiding this comment.
Did you consider alternatives to this name? Would just schema(long schemaVersion, RealmMigration migration) be more accurate? I'm not sure. Maybe it makes sense making "schemaVersion" the primary concept and the migration just a result of that.
There was a problem hiding this comment.
Also. Since we are in the process of making breaking changes. Would it make sense to prepare the API for #2530 ?
Should we already now rename RealmMigration to perhaps RealmManualMigration so in the future we can add ReamAutomaticMigration (just throwing ideas at the wall, we could also postpone and decide later. E.g. we can introduce both of these interfaces in a new update and just let RealmMigration be an alias for RealmManualMigration until the next major release).
There was a problem hiding this comment.
Since the migration would never be fully automated for all cases, I guess a RealmAutomaticMigration would also need some customization points, so maybe better off separating the automatism into a helper and allowing people to take advantage of this in other scenarios. Thus, keeping the RealmMigration interface for customization but supplying a DefaultRealmMigration implementation for simple cases where the automatic migration helper is assumed to handle everything (simple additions/deletions, etc).
There was a problem hiding this comment.
I think I need to see some code to understand that 😄
There was a problem hiding this comment.
Did you consider alternatives to this name? Would just
schema(long schemaVersion, RealmMigration migration)be more accurate? I'm not sure. Maybe it makes sense making "schemaVersion" the primary concept and the migration just a result of that.
Shorter names are good, but maybe some keeping it to align with other platforms. If not bound by that I would go for version but maybe that is too overloaded?
There was a problem hiding this comment.
JS has separate: schema, schemaVersion and migration blocks
Cocao has: schemaVersion and migrationBlock
.NET has SchemaVersion and MigrationCallback
That probably hints to us to keep schemaVersion(version, migration). Thoughts?
There was a problem hiding this comment.
Yep. Lets just keep it, to avoid too may different names.
Scheme version/migration configuration clarifications:
Added additional version/migration configuration test to clarify existing semantics:
RealmMigrationwill never be called unless specifying aschemeVersiontooschemeVersionwill trigger aRealmMigrationif present or will otherwise silently bump the version.Proposing deprecation of old
schemeVersion(long)andmigration(RealmMigration)in favour ofschemeVersion(long, RealmMigration)to highlight semantically connection.