Pause or Terminate Sync

On this page

Pause Sync

Terminate Sync
Re-Enable Sync

Atlas Device Sync, Atlas Edge Server, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

If you want to disable Atlas Device Sync for your app, you can temporarily pause or permanently terminate it. You can also re-enable Device Sync after disabling it.

You can temporarily pause Device Sync if you need to pause your cluster. With a temporary pause, you can re-enable without resetting your Device Sync configuration or losing Device Sync metadata.

You can permanently terminate and re-enable Device Sync for troubleshooting or if you want to change your Device Sync configuration.

Device Sync pauses automatically after 30 days of inactivity.

Pause Sync

You can pause Device Sync for a period of time without disabling it entirely. When you pause Device Sync, you stop syncing changes between Atlas and your application.

Important

If you need to pause your cluster, pause Device Sync first. Otherwise, you must terminate and re-enable Device Sync and perform a client reset.

Pausing Device Sync rejects any incoming client connections. This means that pausing Device Sync for your App stops syncing changes for all clients.

Press the Pause Sync Button

In the Device Sync tab of the App Services UI, press the Pause Sync button at the top of the screen.

Then, confirm that you want to pause sync.

You can use the App Services API to programmatically pause Device Sync.

Get an Authentication Token

Every request to the App Services Admin API must include a valid and current authorization token from the MongoDB Cloud API as a bearer token in the Authorization header.

For details on how to get an authentication token, refer to Get Authentication Tokens.

Get Group, App, and Service IDs

Get the Group and App ID for your app.
Get the Service ID for your Sync service. You can programmatically get all services using the adminListServices endpoint.

Alternately, you can extract Group, App, and Service IDs from the URL when you view the UI.

Go to the App Services App where Device Sync is configured.
Select Linked Data Sources in the sidebar under Manage.
Select the mongodb-atlas CLUSTER.

The URL in your browser's toolbar should now resemble:

https://services.cloud.mongodb.com/groups/$GROUP_ID/apps/$APP_ID/services/$SERVICE_ID/config

Get the Sync Service Configuration

Send a GET request to the adminGetServiceConfig endpoint to get the Device Sync service configuration. This returns a Service configuration object similar to:

{
  "clusterId": "<MY-CLUSTER-ID>",
  "clusterName": "Cluster0",
  "clusterType": "atlas",
  "flexible_sync": {
    "state": "enabled",
    "database_name": "todo",
    "permissions": {
      "rules": {},
      "defaultRoles": []
    },
    "client_max_offline_days": 30,
    "is_recovery_mode_disabled": false
  },
  "groupName": "<MY-GROUP-NAME>",
  "orgName": "<MY-ORG-NAME>",
  "readPreference": "primary",
  "wireProtocolEnabled": false
}

For details about the Sync configuration returned by this endpoint, refer to Sync Configuration File Reference.

Edit the Sync Service Configuration

Remove just the flexible_sync part of the configuration to a new JSON object. This configuration contains a state field that reflects the current state of the Sync protocol for the application. Set this value to disabled. This should now resemble a JSON blob similar to:

 {
   "flexible_sync": {
     "state": "disabled",
     "database_name": "todo",
     "permissions": {
       "rules": {},
       "defaultRoles": []
     },
     "client_max_offline_days": 30,
     "is_recovery_mode_disabled": false
   }
 }

Update the Configuration on Atlas

Send the updated Sync Service configuration as a payload in a PATCH request to the adminUpdateServiceConfig endpoint.

To pause Device Sync from the client side, using logic that situationally pauses Device Sync during a session, see your preferred SDK:

After pausing Device Sync, you can re-enable it. Pausing Device Sync maintains the configuration settings and all of the Device Sync metadata, which contains the sync history. When you re-enable paused Device Sync, your clients can reconnect normally.

Warning

If your oplog rolls past the time that you paused Device Sync, you must terminate and re-enable Device Sync. For example, if you only keep 12 hours of oplog for your cluster, and you pause Device Sync for longer than 12 hours, you must terminate and re-enable Device Sync.

Terminating and re-enabling paused Atlas Device Sync for your App erases Atlas Device Sync metadata and requires you to specify configuration settings again. Clients must perform a client reset when they reconnect after Atlas Device Sync has been terminated. For more information, see: Terminate Sync.

Terminate Sync

If you have enabled Device Sync, you may have to terminate and re-enable Device Sync under a few different circumstances:

An upgrade from a Shared Tier Atlas Cluster to a Shared or Dedicated instance
A move to an Atlas cluster that is distributed across regions/cloud providers
An upgrade to NVMe Atlas clusters
An oplog rollover
A paused Device Sync session on a shared tier cluster due to infrequent usage
Troubleshooting, at the request of MongoDB Support
Switching between Sync modes. For instance, if you are switching from Partition-Based Sync to Flexible Sync
Dropping a collection you've used with Sync. For example, if you have a Team collection that stores and syncs Team objects, and then you drop that collection, you must terminate and re-enable Sync.

Warning

Restore Sync after Terminating Sync

When you terminate and re-enable Atlas Device Sync, clients can no longer Sync. Your client must implement a client reset handler to restore Sync. This handler can discard or attempt to recover unsynchronized changes.

Terminate Device Sync in your App to stop syncing data across devices.

Press the Terminate Sync Button

In the Sync tab of the App Services UI, click the red Terminate Sync button at the top of the screen.

Confirm That You Want to Terminate Sync

In the modal that appears, type "Terminate Sync" in the text entry, and then click the Terminate Sync button.

If you are using UI deployment drafts then you must deploy the draft to actually terminate Sync.

You have now terminated Device Sync.

You can use the App Services API to programmatically terminate Device Sync.

Get an Authentication Token

Every request to the App Services Admin API must include a valid and current authorization token from the MongoDB Cloud API as a bearer token in the Authorization header.

For details on how to get an authentication token, refer to Get Authentication Tokens.

Get Group, App, and Service IDs

Get the Group and App ID for your app.
Get the Service ID for your Sync service. You can programmatically get all services using the adminListServices endpoint.

Alternately, you can extract Group, App, and Service IDs from the URL when you view the UI:

Go to the App Services App where Device Sync is configured.
Select Linked Data Sources in the sidebar under Manage.
Select the mongodb-atlas CLUSTER.

The URL in your browser's toolbar should now resemble:

https://services.cloud.mongodb.com/groups/$GROUP_ID/apps/$APP_ID/services/$SERVICE_ID/config

Get the Sync Service Configuration

Send a GET request to the adminGetServiceConfig endpoint to get the Device Sync service configuration. This returns a Service configuration object similar to:

{
  "clusterId": "<MY-CLUSTER-ID>",
  "clusterName": "Cluster0",
  "clusterType": "atlas",
  "flexible_sync": {
    "state": "enabled",
    "database_name": "todo",
    "permissions": {
      "rules": {},
      "defaultRoles": []
    },
    "client_max_offline_days": 30,
    "is_recovery_mode_disabled": false
  },
  "groupName": "<MY-GROUP-NAME>",
  "orgName": "<MY-ORG-NAME>",
  "readPreference": "primary",
  "wireProtocolEnabled": false
}

For details about the Sync configuration returned by this endpoint, refer to Sync Configuration File Reference.

Edit the Sync Service Configuration

This configuration contains a state field that reflects the current state of the Sync protocol for the application. Set this value to an empty string "". This should now resemble a JSON blob similar to:

 {
   "flexible_sync": {
     "state": "",
     "database_name": "todo",
     "permissions": {
       "rules": {},
       "defaultRoles": []
     },
     "client_max_offline_days": 30,
     "is_recovery_mode_disabled": false
   }
 }

Update the Configuration on Atlas

Send the updated Sync Service configuration as a payload in a PATCH request to the adminUpdateServiceConfig endpoint.

After terminating Device Sync, you can re-enable it. Terminating Device Sync destroys the configuration settings and all of the Device Sync metadata, which contains the sync history. Re-enabling Sync requires you to complete the Sync configuration steps again. Clients that have previously connected cannot reconnect until they perform a client reset.

Re-Enable Sync

After you have paused or terminated Device Sync, you can re-enable it. Re-enabling Device Sync enables your App to begin syncing changes to Atlas again. After you re-enable Device Sync, your App begins accepting incoming client connections again.

When you pause Device Sync, App Services preserves your configuration settings, and you can skip the Configure Sync step. When you terminate Device Sync, or when the oplog rolls past the time that you paused Device Sync, you must specify the configuration settings again.

To re-enable Device Sync, follow the steps in the Configure and Enable Atlas Device Sync guide.

You can use the App Services API to programmatically re-enable Device Sync. This procedure assumes you already have a Sync configuration for your cluster that you can use to re-enable Sync with the same settings.

Get an Authentication Token

Every request to the App Services Admin API must include a valid and current authorization token from the MongoDB Cloud API as a bearer token in the Authorization header.

For details on how to get an authentication token, refer to Get Authentication Tokens.

Get Group and App IDs

Get the Group and App ID for your app.

Edit the Sync Service Configuration

This configuration contains a state field that reflects the current state of the Sync protocol for the application. Set this value to enabled. This should now resemble a JSON blob similar to:

 {
   "flexible_sync": {
     "state": "enabled",
     "database_name": "todo",
     "permissions": {
       "rules": {},
       "defaultRoles": []
     },
     "client_max_offline_days": 30,
     "is_recovery_mode_disabled": false
   }
 }

Update the Configuration on Atlas

Send the updated Sync Service configuration as a payload in a PATCH request to the adminUpdateServiceConfig endpoint.

Connect from the Client

Re-enabling Sync enables incoming client connections. However, under some circumstances, your client app code may need to perform a client reset before clients can Sync again.

Your code must handle a client reset when a client has previously connected with Device Sync, and you terminate Device Sync. Terminating Device Sync for your App erases Device Sync metadata that the client needs to reconnect.

This also applies to apps where Device Sync is paused longer than the oplog you keep for your cluster. For example, if you only keep 12 hours of oplog for your cluster, and you pause Device Sync for longer than 12 hours, you must terminate and re-enable Device Sync.

For information on how to perform a client reset in the client, refer to the SDK documentation:

Back

Sync Settings

Handle Errors