Mobile Bytes #1: Additive and Destructive Schema Changes

Note: additive and destructive schema changes are now referred to as non-breaking and breaking changes but the concepts are identical.

Hello Everybody :wave:

I hope you are having a good time getting information on the forums. As you are aware, I started as Community Manager for Realm in Dec and I have been going through some questions on the forum and I found Schema Changes to be frequently asked questions :smiley: and hence the birth of the idea Realm Bytes

Every Week, I would be selecting anyone such topic and along with your collaboration, we would be talking more on that.

Schema Changes can be additive (backwards compatible) or destructive (not backwards compatible) and care should be taken when making changes to Schema for a running application.

A diagram is presented below to help identify whether a schema change is additive or destructive:

Additive Changes: These changes do not trigger a re-sync on the server and your SDK data models should be able to start using the new schema seamlessly. Your client-code (schema on mobile) can be a subset of your Cloud UI (schema on the server) Schema. Learn more

Note: Additive Changes can only Remove Fields if they are optional, removing Required fields will be a destructive change.

When you make an additive schema change there will be a brief update that takes place on the Realm Sync backend and changes may be delayed in propagating to MongoDB Atlas for a short period of time.

Destructive Changes: These changes will require a re-sync i.e Terminate and Re-enable Sync to map the new schema in place, and we strongly recommend making sure you have client reset logic in place first. These changes are preferably made directly in the cloud UI. Learn more

Note: Destructive changes are not allowed to be done via the Realm CLI or Code Deployment.

I hope the provided information is helpful.

I would love to hear from your experience, what worked and what didn’t. If there is a topic you want me to cover next week, please feel free to reach out. :smiley:

Happy Realming!



G’Day, Folks, :wave:

I would love to hear your experience with Additive and Destructive Schema changes :smiley: I would like to share some more insights today that I discovered while experimenting with my restaurant app.

When you have development mode on, you can only make additive changes. If you try to make a destructive change, it will throw an error like this:

An exception has been thrown: The following changes cannot be made in additive-only schema mode:
    - Property 'User._id' has been changed from 'object id' to 'string'.

I wanted to change the type of the _id field in my User Schema and this was a destructive change and I was not able to do it from within the application.

I changed the schema directly on the cloud UI and it prompted me to resync my data I had to do that. Now when I try to sync my mobile client app, the server logs show the below error:

client file not found. The server has forgotten about the client-side file presented
 by the client. This is likely due to using a synchronized realm after terminating 
and re-enabling sync. Please wipe the file on the client to resume 
synchronization. { sessionIdent: 1, clientFileIdent: 25 } (ProtocolErrorCode=208)

This is client-reset message. I have not implemented client-reset in my code as this was a test app, so I uninstalled the application and synced again and I am able to run the app without any error.

This is not a friendly method for production apps, so the recommendation is to have client-reset implementation in the application.

Cheers, :performing_arts: