Dropping the database and restarting sync will generally result in all data being lost, so it is not something I would particularly recommend doing.
When adding properties to the schema you should not be terminating or restarting sync. That is the step which causes client resets, and it is not required when adding properties. You should run a pipeline to add the required field to the documents* and then deploy the schema change without ever terminating sync, and no downtime at all is required.
If you don’t restart sync but add a required field which isn’t present in your documents you’ll see similar behavior, just without the client reset. The documents missing the field will be marked as unsyncable and the client-side objects corresponding to them will be deleted. After the server-side schema change has been synced to the client, objects created by the client will contain the new field even without any updates to the client app (with a default value of zero/nil/false/empty as appropriate for the type).
* There is a race condition here in active production usage: between when you run the pipeline and when the schema change is completed new documents may be created by clients which are missing the new field. If a temporary bit of weirdness is acceptable (some objects may disappear and then reappear on the client) you can rerun the pipeline after changing the schema. If not, you can use triggers to add the field to newly created documents during the migration period.
That function is for manual client resets and you shouldn’t call it from the automatic client reset handler. The documentation for manual client resets is somewhat vague because it proved to be something which was very difficult to implement in apps, and even more difficult to provide any sort of general guidance on how to implement them. The flow for manual resets roughly is:
- Make a backup copy of the current local file
- Delete the local file and redownload it from the server
- Do some sort of data recovery to extract unsynchronized changes from the backup file.
Step 2 requires that the existing Realm be closed, which is a somewhat complicated thing (we can’t just unilaterally close the file as you may be reading from it on another thread). As a result, we normally do most of this the next time the Realm is opened rather than immediately upon receiving the error. SyncSession.immediatelyHandleError tells us to instead do it right away. This requires that you’ve ensured that you no longer have any references to the Realm, which in practice is a rather difficult thing to do.