Docs Menu

Update Your Schema

On this page

When developing an application using Atlas Device Sync, you may need to make changes to your schema at some point, such as when you need to:

  • Add a new property to an already-synced object
  • Remove a property from an already-synced object
  • Change the type stored in a property
  • Update an optional property to required

To make it easier to understand how schema changes affect your app, we characterize them as "breaking" versus "non-breaking" changes.

App Services provides for non-breaking schema changes to synced realms, allowing old clients to sync with newer ones.

Breaking schema changes, however, take some planning and work, and should be avoided whenever possible.

Breaking schema changes are difficult because 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. Clients that are updated need to work with the new schema changes.

Note
Make breaking changes via the Atlas App Services UI

Because breaking or destructive schema changes require special handling, App Services does not support making these changes via Realm CLI or automated deploy with GitHub. Instead, you should make breaking changes in the Atlas App Services UI.

A breaking change is a change that you can make in your server-side schema that requires additional action to handle. Failing to handle these changes properly can result in clients being unable to open a realm, or the appearance of data loss when server-side documents are unable to sync to client-side applications.

A non-breaking change is a change that you can make in your server-side schema or your object model without requiring additional handling in your app. App Services refers to these types of non-breaking changes as additive changes. They apply automatically to synced realms; you can make these non-breaking schema changes with no additional client-side configuration changes.

Note
Applying non-breaking changes to the client may require migration

When you only make non-breaking changes to the server-side schema, no additional action is required. However, if you then try to apply these changes to your client object model, you may need to perform a migration. If the client device has an existing realm file, you must perform a migration. For details, see the Modify an Object Schema page in your preferred SDK.

This table shows whether each type of change is breaking or non-breaking when you make it only in the server-side schema or in the object model. Some changes that are non-breaking on the client-side are breaking on the server-side. Additionally, some changes that are non-breaking on the server-side schema may require additional handling when you apply them to the client-side object model. For more details, see relevant sections below.

Type of Change
Server-Side Schema
Client-Side Object Model
Non-breaking
Non-breaking
Non-breaking
Non-breaking
Non-breaking
Non-breaking
Breaking
Non-breaking
Breaking
Non-breaking
Breaking
Non-breaking
Breaking
Breaking
Breaking*
Breaking*
Breaking
Breaking
Breaking
Breaking
Breaking
Breaking
Tip
Rename a property

While renaming a property is a breaking change, some of the Realm SDKs offer a workaround to remap the property name. See Change a Property Name for more details.

You can add an object type to either the server-side schema or the client object model without doing any additional handling.

If you want to add an object type to both the server-side schema and the client object model, you can add the object type to the object model, and use Development Mode to let App Services infer the server-side schema updates. Or you can manually add the object type to both the model and the schema.

If you already have a client-side realm file that contains data, you must increment the client schema version when you open the realm. For more information, see your preferred SDK's migration page.

Note
These changes may trigger a resync

When you add a new object type, we retreive the documents for the collection and re-insert them into App Services to get the new values. This is expected behavior, but it does cause a temporary halt to propogating changes while this process is underway.

You can add a required property to the client object model without doing any additional handling.

Warning
Update existing documents

If you add a new required property to the server-side schema, you must update existing documents with that new property or they do not sync to the client. This may give client users the impression that the data has been lost.

Note
Consider adding an optional property

Adding a required property to the server-side schema requires additional handling detailed below. If you add the property as optional, you can avoid the need to modify existing Atlas documents.

If you want to add a required property to both the server-side schema and the client object model, you can add the required property to the object model, and use Development Mode to let App Services infer the server-side schema updates. Or you can manually add the required property to both the model and the schema.

Important
Even non-breaking changes can require terminating sync

When there are more than 100,000 documents in the __realm_sync.unsynced_documents collection, App Services requires that you terminate and re-enable sync. When you add a required property, the re-sync process can push your collection over this limit. In this case, you must terminate and re-enable sync, even though the change you're making is a non-breaking change.

If you add a new required property to the server-side schema, you must update existing documents with that new property or they do not sync to the client. This may give client users the impression that the data has been lost.

If an Atlas document does not have the new required property, the entire document no longer syncs to the client application. Resolve this issue by adding a new field to each document that matches the new schema, and populating it with a default value.

After you've made these changes, the appropriate documents should once again sync to the client application.

If you already have a client-side realm file that contains data, you must increment the client schema version when you open the realm. For more information, see your preferred SDK's migration page.

Note
These changes may trigger a resync

When you add a new required property, we retreive the documents for the collection and re-insert them into App Services to get the new values. This is expected behavior, but it does cause a temporary halt to propogating changes while this process is underway.

You can add an optional property to either the server-side schema or the client object model without doing any additional handling.

If you want to add an optional property to both the server-side schema and the client object model, you can add the optional property to the object model, and use Development Mode to let App Services infer the server-side schema updates. Or you can manually add the optional property to both the model and the schema.

If you already have a client-side realm file that contains data, you must increment the client schema version when you open the realm. For more information, see your preferred SDK's migration page.

Note
These changes may trigger a resync

When you add a new optional property, we retreive the documents for the collection and re-insert them into App Services to get the new values. This is expected behavior, but it does cause a temporary halt to propogating changes while this process is underway.

If you remove an object type from the server-side schema, this is a breaking or destructive change. However, you can remove an object type from the object model as a non-breaking change.

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can remove the object type from the client-side object model and leave it in place on the server-side schema.

If you already have a client-side realm file that contains data, you must increment the client schema version when you open the realm. For more information, see your preferred SDK's migration page.

If you remove a required property from the server-side schema, this is a breaking or destructive change. However, you can remove a required property from the object model as a non-breaking change.

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can remove the property from the client-side object model and leave it in place on the server-side schema.

To maintain backward compatibility, removing a property from a client-side object model does not delete the property from the database. Instead, new objects retain the removed property, but App Services automatically sets the property's value to null. App Services sets properties that are non-nullable to an appropriate empty value, such as a 0 for integer values or an empty string for string values. This is considered a non-breaking or additive change to the object model.

If you already have a client-side realm file that contains data, you must increment the client schema version when you open the realm. For more information, see your preferred SDK's migration page.

If you remove an optional property from the server-side schema, this is a breaking or destructive change. However, you can remove an optional property from the object model as a non-breaking change.

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can remove the property from the client-side object model and leave it in place on the server-side schema.

To maintain backward compatibility, removing a property from a client-side object model does not delete the property from the database. Instead, new objects retain the removed property, but App Services automatically sets the property's value to null. App Services sets properties that are non-nullable to an appropriate empty value, such as a 0 for integer values or an empty string for string values. This is considered a non-breaking or additive change to the object model.

If you already have a client-side realm file that contains data, you must increment the client schema version when you open the realm. For more information, see your preferred SDK's migration page.

If you change an object type's name, this is a breaking or destructive change to both the server-side schema and the client-side object model.

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can let the existing collection remain in place with the existing schema, and create a partner collection with the new schema.

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 breaking schema change using the partner collection strategy, see Make Breaking Schema Changes.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, you must manually update the schema. Development Mode does not automatically update your schema for breaking changes.

If you already have a client-side realm file that contains data when you implement a schema change using the partner collection strategy, you must perform a migration when you open the realm. For more information, see your preferred SDK's migration page.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, your client application must perform a client reset.

If you change a property's name, this is a breaking or destructive change to both the server-side schema and the client-side object model.

Warning
Update existing documents

If you change a property name in the server-side schema, you must update existing documents with that new property name or they do not sync to the client. This may give client users the impression that the data has been lost.

Tip
Change a property name

While changing a property name is a breaking change in both the server-side schema and the client-side object model, some SDKs do offer an API to map the name defined in a model class to a different internal name. This allows you to avoid renaming a property and triggering migrations, but instead map the realm property name to something different to match your code. You can use this API in these SDKs:

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can let the existing collection remain in place with the existing schema, and create a partner collection with the new schema.

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 breaking schema change using the partner collection strategy, see Make Breaking Schema Changes.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, you must manually update the schema. Development Mode does not automatically update your schema for breaking changes.

If you choose to terminate and re-enable sync, you must update existing Atlas documents to enable them to Sync with your client applications. Without this additional handling, those documents do not Sync and it may appear in the client that the data has been lost.

If an Atlas document maintains the old property name, the entire document no longer syncs to the client application. You could resolve this issue in a few ways:

  • Change the old field name on each document to match the new schema
  • Add a new field to each document with a name that matches the new schema, and copy the value from the old field into it

After you've made these changes, the appropriate documents should once again sync to the client application.

If you already have a client-side realm file that contains data when you implement a schema change using the partner collection strategy, you must perform a migration when you open the realm. For more information, see your preferred SDK's migration page.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, your client application must perform a client reset.

If you change a property's type while keeping the name, this is a breaking or destructive change to both the server-side schema and the client-side object model.

Warning
Update existing documents

If you change a property's type in the server-side schema, you must update existing documents with that new property type or they do not sync to the client. This may give client users the impression that the data has been lost.

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can let the existing collection remain in place with the existing schema, and create a partner collection with the new schema.

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 breaking schema change using the partner collection strategy, see Make Breaking Schema Changes.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, you must manually update the schema. Development Mode does not automatically update your schema for breaking changes.

If you choose to terminate and re-enable sync, you must update existing Atlas documents to enable them to Sync with your client applications. Without this additional handling, those documents do not Sync and it may appear in the client that the data has been lost.

If an Atlas document maintains the old property type, the entire document no longer syncs to the client application. You could resolve this issue in a few ways:

  • Change the old field type on each document to match the new schema
  • Add a new field to each document with a type that matches the new schema, and copy the value from the old field into it, transforming its type

After you've made these changes, the appropriate documents should once again sync to the client application.

If you already have a client-side realm file that contains data when you implement a schema change using the partner collection strategy, you must perform a migration when you open the realm. For more information, see your preferred SDK's migration page.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, your client application must perform a client reset.

If you change a property from optional to required, this is a breaking or destructive change to both the server-side schema and the client-side object model.

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can let the existing collection remain in place with the existing schema, and create a partner collection with the new schema.

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 breaking schema change using the partner collection strategy, see Make Breaking Schema Changes.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, you must manually update the schema. Development Mode does not automatically update your schema for breaking changes.

If you already have a client-side realm file that contains data when you implement a schema change using the partner collection strategy, you must perform a migration when you open the realm. For more information, see your preferred SDK's migration page.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, your client application must perform a client reset.

If you change a property from required to optional, this is a breaking or destructive change to both the server-side schema and the client-side object model.

A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. This triggers a client reset, which can result in client-side data loss. As a result, we do not recommend making breaking server-side schema changes.

Instead, you can let the existing collection remain in place with the existing schema, and create a partner collection with the new schema.

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 breaking schema change using the partner collection strategy, see Make Breaking Schema Changes.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, you must manually update the schema. Development Mode does not automatically update your schema for breaking changes.

If you already have a client-side realm file that contains data when you implement a schema change using the partner collection strategy, you must perform a migration when you open the realm. For more information, see your preferred SDK's migration page.

If you choose to terminate and re-enable sync instead of using the partner collection strategy to resolve this type of breaking change, your client application must perform a client reset.

  • Non-breaking schema changes on synced realms are backward compatible, allowing old clients to sync with newer ones.
  • Non-breaking changes to the schema of a synced realm do not require any additional configuration. However, you may need to migrate client realm files even when making non-breaking changes.
  • Breaking changes are modifications to existing properties of a schema.
  • To perform breaking 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.
  • You can implement a breaking change by terminating and re-enabling sync and performing a client reset, but it is not recommended.
←  Generate SDK Object ModelsMake Breaking Schema Changes →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.