Add a New Field to a Realm JS Database using Migrations

Add a New Field to a Realm JS Database using Migrations

While building my app ThinkBack I decided to use Realm as my underlying data-store. ThinkBack helps users commit notes or ideas to long term memory through passive, daily recall. To support changes and new features in the app I need to modify the existing Realm JS object model that defines the schema.

Modify Schema and Perform Migration of Existing Database

The original Note schema and Realm are defined as follows:

const noteSchema: Realm.ObjectSchema = {
  name: "Note",
  properties: {
    id: "string",
    content: "string",
    createdOn: "date",
    modifiedOn: "date",
    ...
  },
  primaryKey: "id",
}

const realm = new Realm({ path: "default", schema: [ noteSchema
... ], schemaVersion: 0, })

I wanted to modify this schema to introduce a new field called “title”. Moving forward a note must have a title and, if one isn’t provided, a default title “No title” will be applied. Adding a new field to a database is something Realm JS can handle automatically for you but applying a default value requires a little manual intervention. In order to apply a default value for existing records in the database I leveraged Realm Migrations.

Here’s what the new schema and Realm looks like:

const noteSchema: Realm.ObjectSchema = {
  name: "Note",
  properties: {
    id: "string",
title: "string", content: "string", createdOn: "date", modifiedOn: "date", ... }, primaryKey: "id", }

const realm = new Realm({ path: "default", schema: [ noteSchema ... ], onMigration: (oldRealm: Realm, newRealm: Realm) => {
const newNotes = newRealm.objects<Note>("Note"); for (let i = 0; i < newNotes.length; i++) { newNotes[i].title = "No title"; } }, schemaVersion: 1, })

According to the Mongo DB Realm docs when you create a Configuration with a schema version greater than the realm’s current version, Realm runs a migration function that you define. The function has access to the realm’s version number and incrementally updates objects in the realm to conform to the new schema. From the examples above the original schema version was 0 (default), and in the updated schema the version is 1. When Realm detects a newer version of an existing database the onMigration function defined above will be invoked, allowing opportunity to apply a default title to each note in the Realm.

I'd love to hear your thoughts