Docs Menu

Synced Schema Changes

On this page

  • Overview
  • Additive Changes
  • Destructive Changes
  • Partner Collections
  • Summary

When developing an application using Realm Sync, you may need to make changes to your schema at some point: you have a new property to add to an already-synced object, you decide to change the type stored in a property, or you now need to make a property required, for example.

The Realm APIs provide for backward-compatible schema changes to synced realms, allowing old clients to sync with newer ones. Destructive schema changes, however, take some planning and work.

The difficulty with implementing a destructive schema changes is that older clients (those that have not been updated to your new code and schema) still need access to the data via the old schema definition, while clients that are updated need to work with the new schema changes.

Additive changes, such as adding a class or adding a field to an existing class, are applied automatically to synced realms; you can make these additive schema changes with no additional configuration changes.

Note
Removing a Property from Your Schema Is Considered an Additive Change

To maintain backward compatibility, removing a field from a schema doesn’t delete the field from the database and instead instructs Realm to ignore that field. New objects retain the removed field, but Realm automatically sets the field's value to null. Realm sets fields that are non-nullable to an appropriate empty value, such as a 0 for integer values or an empty string for string values.

Destructive changes to a schema are usually modifications of existing fields, such as:

  • Changing a property’s type but keeping the same name
  • Changing a primary key
  • Changing a property from optional to required (or vice-versa)

Synchronized realms only support additive changes to a schema. Therefore, attempting to perform a destructive change on a synchronized realm leads to errors like the following:

{
message: 'The following changes cannot be made in additive-only schema mode:\n' +
"- Property 'Task._id' has been changed from 'int' to 'string'.",
errorCode: 1
}

If you are developing an application using Realm Sync and need to make a destructive schema change, you have two choices: terminate sync in the backend and then re-enable it from the start, or create a "partner collection".

A partner collection is a collection that contains the same data as the original collection, but has the new schema definition in place. Partner collections use database triggers to ensure that data flows in both directions, meaning that when one collection is written to, the other is also written to (with the data modifications required for the new schema).

To implement a schema change, see Migrate Schemas with Partner Collections.

  • Schema changes on synced realms are backward compatible, allowing old clients to sync with newer ones.
  • Additive changes to the schema of a synced realm do not require any additional configuration.
  • Synchronized realms only support additive changes to a schema.
  • Destructive changes are modifications to existing fields of a schema.
  • Synchronized realms do not support destructive changes directly.
  • To perform destructive schema changes to a synced realm, create a partner collection with the necessary schema changes and manually copy the data from the first collection to the second collection.
  • To keep partner collections up-to-date with each other, set up database triggers to copy changed data from one collection to its partner.
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.