ObjectBox Data Model Migration

The ObjectBox database manages its schema mostly automatically. When you add new entities or properties on your side, ObjectBox simply updates its database structure. This also works when you remove entities or properties. Still, there are some situation where ObjectBox needs extra information to make things unambiguous.

UIDs for identification

ObjectBox keeps track of UIDs for entities and properties in a file called “objectbox-models/default.json”. Search for an entity/property and check the “id” attribute: the second part after the colon is the UID. We have an in-depth documentation on UIDs and concepts, but for now it is only important to know where to find them.

Renaming Entities and Properties

When you simply rename an entity class, ObjectBox only sees that the old entity is gone and a new entity is available. This can be interpreted in two ways:

  • The old entity is removed and a new entity should added, old data is discarded (default behavior)
  • The entity was renamed, old data remains

To tell ObjectBox that you want to do a rename, you need to give the entity or property a more robust identification that just a name. This is exactly what UIDs are for. And once you have assigned an UID, all future renames are already covered.

The same is true for properties.

How-to and Example

Renaming requires two additional steps before the actual rename:

  1. Before the rename, put an empty @Uid  (no value) on the entity/property you want to rename
  2. Build the project: the UID value will be written to the @Uid annotation
  3. Do the actual rename

Step 1:

Step 2:

Step 3:

You can also do this manually (may be required for other languages than Java at the moment):

  • Find the UID in the JSON file for the entity/property you want to rename
  • Use the @Uid annotation to put the UID on the entity/property

Changing Property Types

When you change a property’s type, you must tell ObjectBox as a precaution. Because data cannot be migrated, this precaution avoids unintended data losses. Basically, you tell ObjectBox to create a new property and abandon the old one. You have two options:

  • Rename the property, so it is treated as a new property (no previous UID assignment)
  • Tell ObjectBox to use a new UID for the property

How-to and Example

  1. Put @Uid(-1)  on the property you want the type migration for (before or after the type migration)
  2. Build the project: a newly created UID value will be written to the @Uid annotation

Step1:

Step 2:

You can also do this manually (may be required for other languages than Java at the moment):

  1. Find the UID in the JSON file for the entity/property you want the type migration for
  2. Create a variation of the UID, for example by adding or subtracting 1 (don’t worry, ObjectBox will check for collisions, which are very unlikely in the 64 bit number space anyway)
  3. Use the @Uid annotation to put the UID on the entity/property
Spread the love
Sign up for fresh ObjectBOX news here. No spam, just fresh developer news once in a while.
x