Docs Menu

Docs HomeAtlas App Services

Add Sync to a Local-Only App

On this page

  • Overview
  • Create an App
  • Enable Authentication
  • Choose a Sync Mode
  • Update the Client App
  • Copy Existing Data
  • App Logic

If you have a mobile app that uses a local realm and you want to convert the app to use Sync, there are a few steps you need to follow. You first need to set up an App backend. Then, make code changes in your client applications.

In the following sections, you will learn to do the following on the backend:

  1. Create a new App in MongoDB Atlas,

  2. Configure at least one authentication provider

  3. Choose a Sync type.

And then, in your client app, you will:

  1. Update your Realm object models,

  2. Connect to the new synced realm with a sync configuration file,

  3. Authenticate the user.

Finally, if needed, you will also need to copy your local data to the new synced realm.

To sync your data between devices and MongoDB Atlas, you first need to create an App. This App provides a gateway to the data and data security in the form of user authentication, data encryption, and access control.

To get started creating the backend app, follow the steps in Create an App.

Atlas Device Sync requires authenticated users. Atlas App Services provides many different Authentication Providers such as email/password and OAuth; once you have configured one or more providers, you can then control exactly who has access to which data.

To set up an authentication provider, choose one of the providers and follow the configuration steps for the provider(s) of your choice.

There are two Sync Modes: Flexible Sync and the older Partition-Based Sync. We recommend using Flexible Sync.

With Flexible Sync, clients synchronize subsets of data based on queries to queryable fields. When configuring Flexible Sync, you decide which fields clients can query upon. Development Mode allows App Services to deduce the queryable fields based on your queries. To learn more, follow the steps in Procedure.

Now that you have the backend set up for Device Sync, you need to make a few changes in your client app. Follow the steps in the Quick Start for your language/platform:

  • Quick Start with Sync - Java SDK

  • Quick Start - Swift SDK

  • Quick Start - .NET SDK

  • Quick Start - React Native SDK

  • Quick Start - Node.js SDK


Alternate SDK Implementations

Some SDKs support an easier implementation for adding sync to a local-only realm than the steps outlined on this section.

None of the data in your local realm automatically transfers to a new synced realm [1]. You must copy the data you want to preserve to the new realm. The following diagram and steps outline the process for copying all of the data from a local realm to a synced realm.

[1] With the exception of apps migrated from local to synced realms using the easier implementations outlined in "Alternate SDK Implementations".
Flow chart showing the steps to convert from local to sync
  1. Check if a synced realm already exists.

  2. If not, create one. Open a connection to it and to the local realm.

  3. Read each record from the local realm and modify it to match the schema of the synced realm.

  4. Copy the modified record to the new synced realm. Sync automatically copies the record to MongoDB Atlas when connected to your App.

  5. Confirm that all records you want to preserve are in the new realm.

  6. Delete the local realm file.

  7. On each subsequent app load, check if the local realm has been deleted.

←  Stream Data Unidirectionally from a Client to AtlasEvent Library →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.