[DOCS-14211] Add documentation for how to handle destructive changes in Realm Created: 10/Feb/21  Updated: 27/Oct/23  Resolved: 08/May/23

Status: Closed
Project: Documentation
Component/s: Realm
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major - P3
Reporter: Mansoor Omar Assignee: Unassigned
Resolution: Gone away Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Participants:
Days since reply: 39 weeks, 2 days ago
Story Points: 3

 Description   

Description

We only have this documented in Realm.io and even then it's quite hidden:

https://docs.realm.io/sync/using-synced-realms/syncing-data#destructive-changes

I believe this topic should be covered in docs.mongodb and include how to update schema with destructive changes. For e.g. a customer might update their client code changing the data type of an existing field which is already in the Realm schema. Development mode will not update this for them and they'll need to take extra steps such as deleting the field from the current schema, terminating sync, and running app etc.

It would be good to add such documentation under Realm Sync and cover the subject thoroughly with multiple options on how to perform destructive changes.

Scope of changes

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)



 Comments   
Comment by Emet Ozar [ 08/May/23 ]

This will be addressed in upcoming info. architecture restructure

Comment by Mansoor Omar [ 09/Nov/21 ]

I see the ticket has been closed as "gone away" - not sure what this means?

If documentation has been added/modified, could we please mention in the comments what exactly was done and a link to the document? 

Comment by Ian Ward [ 13/Sep/21 ]

Understood mansoor.omar - mohammad.hunan do we have anything in the docs that spells this out in development mode? Presumably, the developer is not worried about losing data since they are in development so terminating and re-enabling sync is probably fine but you will need to wipe the state on the device and fix the schema to match on both ends before re-enabling sync on the serverside.

Comment by Mansoor Omar [ 13/Sep/21 ]

Example:

https://www.mongodb.com/community/forums/t/what-is-the-proper-way-to-fix-destructive-changes/117251 

Comment by Mansoor Omar [ 13/Sep/21 ]

ian.ward The scenario I'm referring to is mostly one that we encounter when customers are still in development where they make the destructive change on the client side and have development mode enabled. 

We don't have anything documented which tells them they need to manually remove existing schema definitions in the cloud schema (whether it is by deleting one field or removing the entire collection schema) before dev mode will work. I raised this task to request that we outline both scenarios and the steps involved for making destructive changes in the client VS making them in the cloud/UI.

Comment by Ian Ward [ 13/Sep/21 ]

Yeah, the docs could be updated to say "terminate sync in the backend and then re-enable it once the sync schema has been changed matches on both ends, "

mansoor.omar Is that what you are getting at? The doc:
https://docs.mongodb.com/realm/sync/migrate-schema-partner-collection/#std-label-migrate-schema-partner-collection

Gives a very detailed walkthrough of how to make destructive schema changes in production with terminating sync (and thus data loss).

Comment by Mansoor Omar [ 12/Sep/21 ]

To clarify further, the documentation seems to address the scenario where a destructive change is made in the Client (because of the error it mentions)...

{
 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
}

...but the remediation step (of terminating sync) is given for the scenario where a destructive change is made in the UI - which would be the correct one.

Comment by Mansoor Omar [ 12/Sep/21 ]

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".

AFAIK terminating sync by itself will not help with doing a destructive change since the server schema will remain.

You would need to manually remove the field or collection schema (from the UI) that the destructive change involves, then terminate sync. 

ian.ward do you agree?

Comment by Mohammad Chughtai (Inactive) [ 10/Sep/21 ]

This documentation exists and is already published - https://docs.mongodb.com/realm/sync/synced-schema-overview/#destructive-changes and https://docs.mongodb.com/realm/sync/migrate-schema-partner-collection/

Generated at Thu Feb 08 08:09:47 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.