Docs Home → Atlas App Services
Sync Data in a Client Application with Atlas and Other Devices
On this page
- Set up Atlas Access
- Create an Atlas App Services App
- Configure Device Sync
- Enable an Authentication Provider
- Generate an App Services Schema
- Add Sync to the Client Application
- Connect the client to an App Services backend
- Authenticate a User
- Open a Synced Realm
- Copy Existing Data Into a Synced Realm
- Use the Synced Realm
If you have a mobile or client application that uses Realm Database, and you would like to synchronize its data across other devices and back it up to MongoDB Atlas, you can do so using Device Sync. Follow these high-level steps to get started:
Set up Atlas Access
Create an Atlas App Services App
The App Services application is the gateway that enables your client device to connect to MongoDB Atlas. When you create an App, you name it, link it to an Atlas cluster, and specify the deployment model and deployment region that work best for your application.
To learn how to create an App Services App, see Create an App.
Configure Device Sync
Device Sync is the service that manages synchronizing data to Atlas and across your client devices. Device Sync, together with the Realm SDKs, automatically manages network connectivity, conflict resolution, user authentication, and user permissions and data access.
When you configure Device Sync, you specify the data source that the client devices can access, as well as the permissions that determine what data a user can read and write.
You can configure Device Sync via the Atlas UI, the Atlas App Services Command Line Interface, or the App Services Admin API. The first time you configure Device Sync, you may find it helpful to use the Atlas UI as it provides links and information about various settings and options.
Enable an Authentication Provider
Your client users must authenticate in order to access synced data. App Services provides several authentication providers to enable your users to authenticate. Configure one or more of these authentication providers to enable authentication in your client application.
You can configure authentication providers within the App Services App UI by selecting Authentication in the left navigation menu, and then click a provider to configure it. You can also configure authentication providers by editing the App Services configuration with the Atlas App Services Command Line Interface, or the App Services Admin API.
Generate an App Services Schema
When you already have a client application that uses Realm Database, you can use your Realm Object Model to generate the App Services Schema that maps data between client devices and Atlas. You can do this by enabling Development Mode, a feature that reads your object model data from synced realm data, and generates a schema from that data.
For more information on how to generate an App Services schema from your Realm object model, refer to: Create an App Services Schema from a Realm Object Model.
Add Sync to the Client Application
After this, you've got everything set up that you need on the Atlas side, and you can prepare your client application to sync data. If you already have a client application that persists data using Realm Database, you only need to add a few elements to synchronize that data across devices and with Atlas.
Connect the client to an App Services backend
In your client application code, initialize an App client to connect your client to your App Services backend. This lets your client use App Services features like authentication, and enables opening a synced realm.
Authenticate a User
Your client application user must be authenticated with the App Services backend in order to access synchronized data. Add logic to your client app to register and log in users.
Open a Synced Realm
Once you have an authenticated user, you can open a synchronized instance of Realm Database to use for that user.
You define a Flexible Sync query subscription in your client code to determine what data to sync to the client application. Device Sync looks for Atlas documents that match the query, which the user has permission to read and possibly write, and synchronizes those documents to the client device as Realm objects. You can add, remove, or update Flexible Sync query subscriptions to change the documents that sync to the device.
C++ SDK
Flutter SDK
Java SDK
Kotlin SDK
.NET SDK
Node.js SDK
React Native SDK
Swift SDK
Copy Existing Data Into a Synced Realm
If you already have client data, you cannot add Device Sync directly to a non-synced realm. You must copy the data from the non-synced realm into the synced realm. If you do not have any client data, you can skip this step.
Some of the SDKs provide methods that enable you to do this when you open a realm. However, many of the Realm SDKs do not currently support using these methods with Flexible Sync.
If your SDK does not support copying a local realm to a Flexible Sync realm, you must write logic to iterate over each object in the non-synced realm and copy it into the synced realm. This is a one-time process. After you copy the data over, you can discard the non-synced Realm and open only the synced realm going forward.
Use the Synced Realm
The syntax to read, write, and watch for changes on a synced realm is identical to the syntax for non-synced realms. While you work with local data, a background thread efficiently integrates, uploads, and downloads changesets. When a user who has write permissions makes changes on the device, the data persists locally. When the user has a network connection, the data automatically syncs back to Atlas and other devices.