realm
Document adding a single, optional field to a RealmObject subclass
Goal
Learn what is necessary for migration (if anything) when adding a single, optional (i.e. may be null) field (e.g. a String, Long, or other RealmObject) to a RealmObject subclass. For example, I add a field as follows:
public class C extends RealmObject {
@PrimaryKey private long id;
+ private String name;
}
I believe this is a very simple case with a possibly simple solution. Either I don't need to do anything or I need to add a migration using addField().
Expected Results
I expected to find the answer in the Migrations section of the documentation. If not there, I expected to find it in the Migration.java of the migration example.
Actual Results
I found some possibly related statements and examples, but there was too much ambiguity to determine whether they applied in my case.
Consider the opening text in the Migrations section of the documentation:
If you have no data stored on disk under the old database schema, just changing your code to the new definition will work fine.
Well, I do have data stored for the object. But I don't have data for this particular new field. The field is optional, so that's okay for the application. But I don't know how Realm works if I just add the field to the class and don't do a migration of the schema.
The two migration code examples shown (adding a new class and adding a new primary key field) are somewhat more complicated than mine, so I'm not sure. The same holds for the larger migration example application.
Suggestions
I can imagine one of two straightforward statements will help alleviate my concern:
- A migration must be done for every schema change, even including something as simple as adding an optional field.
- Some schema changes, such as adding an optional field, do not need a migration. Realm automatically adds the field to the schema.
If you add a statement like one of these to the documentation, it would help to clarify how migration works.
If you add a new field to your object (to the Java class), then on next Realm.getInstance() call, schema validation will fail, and you'll get a migration needed exception. You have to bump the schema version and add the field.
@Zhuinden Just in case it's not clear, I'm talking about adding a field only in code (statically), not using DynamicRealmObject. I actually have code in which I've added a new field, and I didn't get a RealmMigrationNeededException.
You probably had deleteIfMigrationNeeded on your configuration? That's my guess.
@Zhuinden Hmm, that's true. It was there before. I've changed it since, though. Thanks for the insightful help.
Nonetheless, I think my own problem doesn't diminish the need to add a bit of clarification to the documentation. I would add a line to add some stress that every schema change requires migration. Also, by demonstrating it with the simplest possible change – in particular, with a change that would not require a schema change in less schema-strict databases – would help highlight this.
Finally, in a pedagogical sense, the simplest change helps to introduce the issue of migration slowly, to help develop intuition. Starting with a more complicated change can introduce confusion, as it did with me.
