Realm Blog

Realm Java 0.86 — with new Migration API!

We just released a new version of Realm Java to this website and to Maven. This release includes a replacement for the old Migration API, as well as a new Dynamic API to complement it.

Migration API

Migrations are still specified using a migration block in RealmConfiguration, but the interface has changed. Migrations now operate on a new Realm type called a DynamicRealm. DynamicRealm is a special variant of a conventional Realm that allows you to interact and change the schema while still having access to all of the ordinary object creation and query capabilities.

RealmMigration migration = new RealmMigration() {
  @Override
  public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {

     // DynamicRealm exposes an editable schema
     RealmSchema schema = realm.getSchema(); 

     if (oldVersion == 0) {
        // Migrate to version 1
        oldVersion++;
     }

     if (oldVersion == 1) {
        // Migrate to version 2
        oldVersion++;
     }
  }
}

// Configure the migration as normal
RealmConfiguration realmConfig = new RealmConfiguration.Builder(context)
  .schemaVersion(2)
  .migration(migration)
  .build();

Classes and fields are now referenced using their names and can be created and modified in a fluent manner.

RealmSchema schema = realm.getSchema();

// Create Person class with two fields: name and age
schema.create("Person")
    .addField("name", String.class)
    .addField("age", int.class);

// Fields with special properties
schema.get("Person")
    .addField("id", long.class, FieldAttribute.PRIMARY_KEY);

// References to other Realm objects
schema.get("Person")
    .addRealmObjectField("favoriteDog", schema.get("Dog"))
    .addRealmListField("dogs", schema.get("Dog"));

// Creating new data during migrations
DynamicRealmObject person = realm.createObject("Person");
person.setString("name", "John");

// Delete a class and all its data
schema.remove("Person");

It is also possible to run custom transformations on all RealmObjects of a specific type. This can be useful if converting between types, or merging or splitting fields.

schema.get("Person")
  .transform(new RealmObjectSchema.Function() {
    @Override
    public void apply(DynamicRealmObject obj) {
      obj.setInt("age", obj.getInt("age") + 1); // Add 1 to all ages
    }
  });

See RealmSchema and RealmObjectSchema for all options, and take a look at our updated migration example.

Dynamic API

Migrations make use of the new Dynamic API, but it is also available outside migrations. It can be useful in scenarios where you are working with data where the model is not known at compile time, like importing data from CSV files.

Dynamic Realms are opened using the same configuration you use for the conventional Realms, but they ignore any schema, migration, and schema version.

RealmConfiguration realmConfig = new RealmConfiguration.Builder(context).build();
DynamicRealm realm = DynamicRealm.getInstance(realmConfig);

// In a DynamicRealm all objects are DynamicRealmObjects
DynamicRealmObject person = realm.createObject("Person");

// All fields are accessed using strings
String name = person.getString("name");
int age = person.getInt("age");

// An underlying schema still exists, so accessing a field that does not exist will throw an exception
person.getString("I don't exist");

// Queries still work normally
RealmResults<DynamicRealmObject> persons = realm.where("Person").equalTo("name", "John").findAll();

A DynamicRealm trades type safety and performance for flexibility, so only use it in cases where you really need the flexibility.

#enumsmatter

We have updated our query API so it now uses enums instead of booleans when specifying Sort and Case options. This should provide a more readable and type-safe API.

realm.where(Person.class)
  .beginsWith("name", "John", Case.INSENSITIVE)
  .findAllSorted("name", Sort.ASCENDING)

See the full changelog for all the details.


Thanks for reading. Now go forth and build amazing apps with Realm! As always, we’re around on Stack Overflow, GitHub, and Twitter.


Realm Team

At Realm, our mission is to help developers build better apps faster. We provide a unique set of tools and platform technologies designed to make it easy for developers to build apps with sophisticated, powerful features — things like realtime collaboration, augmented reality, live data synchronization, offline experiences, messaging, and more.

Everything we build is developed with an eye toward enabling developers for what we believe the mobile internet evolves into — an open network of billions of users and trillions of devices, and realtime interactivity across them all.

Get more development news like this