Docs Home → Atlas App Services
Update Your Data Model
On this page
- Overview
- Breaking vs. Non-Breaking Change Quick Reference
- Add an Object Type
- How to Add an Object Type
- Handle Client Realm Database Files
- Add a Required Property
- How to Add a Required Property
- Handle Existing Atlas Documents
- Handle Client Realm Database Files
- Add an Optional Property
- How to Add an Optional Property
- Handle Client Realm Database Files
- Remove an Object Type
- How to Remove an Object Type
- Handle Client Realm Database Files
- Remove a Required Property
- How to Remove a Required Property
- Handle Client Realm Database Files
- Remove an Optional Property
- How to Remove an Optional Property
- Handle Client Realm Database Files
- Change an Object Type Name
- How to Change an Object Type Name
- Handle Client Realm Database Files
- Change a Property Name
- How to Change a Property Name
- Handle Existing Atlas Documents
- Handle Client Realm Database Files
- Change Property Type but Keep the Name
- How to Change a Property Type but Keep the Name
- Handle Existing Atlas Documents
- Handle Client Realm Database Files
- Change Property from Optional to Required
- How to Change a Property from Optional to Required
- Handle Client Realm Database Files
- Change Property from Required to Optional
- How to Change a Property from Required to Optional
- Handle Client Realm Database Files
- Summary
Overview
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.
Atlas 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 App Services UI.
Breaking vs. Non-Breaking Change Quick Reference
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.
Add an Object Type
You can add an object type to either the server-side schema or the client object model without doing any additional handling.
How to Add an Object Type
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.
Handle Client Realm Database Files
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.
Add a Required Property
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.
How to Add a Required Property
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.
Handle Existing Atlas 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.
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.
Handle Client Realm Database Files
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 that have new values per the updated schema. We iterate through those documents 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.
Add an Optional Property
You can add an optional property to either the server-side schema or the client object model without doing any additional handling.
How to Add an Optional Property
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.
Handle Client Realm Database Files
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 that have new values per the updated schema. We iterate through those documents 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.
Remove an Object Type
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.
How to Remove an Object Type
A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. Breaking schema changes prevent applications from automatically recovering from a client reset. 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.
Handle Client Realm Database Files
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.
Remove a Required Property
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.
How to Remove a Required Property
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.
Handle Client Realm Database Files
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.
Remove an Optional Property
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.
How to Remove an Optional Property
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.
Handle Client Realm Database Files
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.
Change an Object Type Name
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.
How to Change an Object Type Name
A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. Breaking schema changes prevent applications from automatically recovering from a client reset. 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.
Handle Client Realm Database Files
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 manual client reset. You can define an error handler in your client application code to execute some custom logic in this scenario.
Change a Property Name
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.
How to Change a Property Name
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. Breaking schema changes prevent applications from automatically recovering from a client reset. 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.
Handle Existing Atlas Documents
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.
Handle Client Realm Database Files
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 manual client reset. You can define an error handler in your client application code to execute some custom logic in this scenario.
Change Property Type but Keep the Name
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.
How to Change a Property Type but Keep the Name
A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. Breaking schema changes prevent applications from automatically recovering from a client reset. 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.
Handle Existing Atlas Documents
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.
Handle Client Realm Database Files
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 manual client reset. You can define an error handler in your client application code to execute some custom logic in this scenario.
Change Property from Optional to Required
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.
How to Change a Property from Optional to Required
A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. Breaking schema changes prevent applications from automatically recovering from a client reset. 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.
Handle Client Realm Database Files
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 manual client reset. You can define an error handler in your client application code to execute some custom logic in this scenario.
Change Property from Required to Optional
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.
How to Change a Property from Required to Optional
A breaking server-side schema change requires you to terminate sync in the backend, and then re-enable sync. Breaking schema changes prevent applications from automatically recovering from a client reset. 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.
Handle Client Realm Database Files
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 manual client reset. You can define an error handler in your client application code to execute some custom logic in this scenario.
Summary
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 manual client reset, but it is not recommended.