Reset a Client Realm - Node SDK

On this page

Discard Unsynced Changes

Discard Unsynced Changes after Breaking Schema Changes
Manually Recover Unsynced Changes

Tip

See also: Learn More About Client Resets

To learn about the causes of and strategies for handling client resets, check out the Sync Client Resets page.

A client reset error is a scenario where a client realm cannot sync data with the application backend. Clients in this state may continue to run and save data locally but cannot send or receive sync changesets until they perform a client reset strategy.

You can handle client resets in your application using one of the available client reset strategies:

Discard Unsynced Changes: Restores the realm to a syncable state by discarding changes made since the last sync.
Manually Recover Unsynced Changes: Downloads a new copy of the realm, and moves the unsyncable realm to a backup. Migrate unsynced data from the backup copy of the realm to the new syncable copy.

Discard Unsynced Changes

New in version 10.11.0.

The discard unsynced changes client reset strategy helps you perform a client reset with minimal code and minimal disruption to your application workflow. This strategy restores your local realm to a syncable state without closing the realm or missing notifications.

This strategy comes with a downside: it permanently deletes all local unsynced changes made since the last successful sync of the realm. Do not use the "discard unsynced changes" strategy if your application cannot lose data already written to the client realm file but not yet synced to the backend.

The "discard unsynced changes" strategy can handle every kind of client reset error except for client resets triggered by breaking schema changes. If your application experiences a breaking schema change, this strategy falls back to a mode that mimics the "manually recover unsynced changes" strategy.

To handle client resets with the "discard unsynced changes" strategy, pass a ClientResetConfiguration to the clientReset field of your SyncConfiguration. Include these properties in the ClientResetConfiguration:

mode: Set to "discardLocal".
clientResetBefore(): Optional. Callback function invoked before the SDK executes this strategy, when the SDK receives a client reset error from the backend. Provides a copy of the realm.
clientResetAfter(): Optional. Callback function invoked after the SDK successfully executes this strategy. Provides instances of the realm before and after the client reset.

The following example implements this strategy:

const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    partitionValue: "MyPartitionValue",
    clientReset: {
      mode: "discardLocal",
      clientResetBefore: (realm) => {
        console.log("Beginning client reset for ", realm.path);
      },
      clientResetAfter: (beforeRealm, afterRealm) => {
        console.log("Finished client reset for", beforeRealm.path);
        console.log("New realm path", afterRealm.path);
      },
    },
  },
};

Discard Unsynced Changes after Breaking Schema Changes

Important

Breaking Schema Changes Require an App Schema Update

After a breaking schema change:

All clients must perform a client reset.
You must update client models affected by the breaking schema change.

If your application experiences a breaking schema change, the "discard unsynced changes" strategy cannot handle the resulting client reset automatically. Instead, you must provide a manual client reset implementation in the SyncConfiguration error() callback. The following example demonstrates how you can manually handle this error case by discarding all unsynced changes:

// Once you have opened your Realm, you will have to keep a reference to it.
// In the error handler, this reference is called `realm`
async function handleSyncError(session, syncError) {
  if (syncError.name == "ClientReset") {
    console.log(syncError);
    try {
      console.log("error type is ClientReset....");
      const path = realm.path; // realm.path will no be accessible after realm.close()
      realm.close();
      Realm.App.Sync.initiateClientReset(app, path);
      // Download Realm from the server.
      // Ensure that the backend state is fully downloaded before proceeding,
      // which is the default behavior.
      realm = await Realm.open(config);
      realm.close();
    } catch (err) {
      console.error(err);
    }
  } else {
    // ...handle other error types
  }
}
const config = {
  schema: [DogSchema],
  sync: {
    user: app.currentUser,
    partitionValue: "MyPartitionValue",
    clientReset: {
      mode: "discardLocal",
      clientResetBefore: (realm) => {
        // NOT used with destructive schema changes
        console.log("Beginning client reset for ", realm.path);
      },
      clientResetAfter: (beforeRealm, afterRealm) => {
        // NOT used with destructive schema changes
        console.log("Finished client reset for", beforeRealm.path);
        console.log("New realm path", afterRealm.path);
      },
    },
    error: handleSyncError, // invoked with destructive schema changes
  },
};

Manually Recover Unsynced Changes

Manual recovery requires significant amounts of code, schema concessions, and custom conflict resolution logic. To learn more about the manually recover unsynced changes client reset strategy, see the Advanced Guide to Manual Client Reset Data Recovery.

← Flexible Sync - Node.js SDK Call a Function - Node.js SDK →