Get Started with Atlas Device Sync
On this page
To sync data across devices, you enable Device Sync for your App and then use the sync-related methods and properties in the SDKs.
Tip
Check out the tutorial
If you prefer to learn by example, check out the App Services tutorial, which describes how to build a synced to-do list application with clients for common platforms that App Services supports.
Before You Start
If you don't already have one, sign up for a free MongoDB Atlas account.
Flexible Sync requires MongoDB version 5.0 or later. You can use a free shared M0 cluster to explore and develop your app. We recommend that you use a dedicated tier cluster (M10 and above) for production applications. You cannot use sync with a serverless instance or Federated database instance.
If you don't already have one, create a new App linked to your Atlas cluster.
Configure Your Data Model
Choose an SDK
Realm is an object database optimized for mobile use cases. The Realm SDKs, available for multiple languages and platforms, include everything you need to work with synced "realms" in your client code. You can use multiple SDKs to work with the same set of synced data across devices and platforms.
This guide focuses on configuring sync with an SDK. For in-depth documentation that includes details on how to install and use the Realm SDKs more generally, check out the SDK docs:
Note
The Realm Web SDK does not currently support Realm Database or Atlas Device Sync. However, you can query the same data in an Atlas cluster using MongoDB Data Access.
Define Data Model
A synced realm uses object models that you define to determine the type of objects in the realm. Additionally, Sync requires a server-side document schema for each synced object type so that App Services can translate and apply changes between synced realms and MongoDB Atlas.
To define your synced object models, do one of the following for each object type:
Sync object models from an SDK: In Development Mode, App Services automatically generates a document schema for each synced object type and assigns that schema to a collection in the linked cluster with the same name as the object type. Development mode lets you configure your synced data model from a client application using the same object models and code that you use in your production app. This is useful if you prefer a client-first approach that uses idiomatic object models in your preferred programming language.
For a walkthrough of how to turn on Development Mode, see Enable Development Mode.
Generate object models from a document schema: App Services can automatically generate language-specific object models that you can use in your client applications. The generated models match the document schemas defined for your app's synced cluster. You can define these schemas manually or App Services can sample existing data in the cluster to create them automatically. This is useful if you prefer a server-first approach and/or plan to build apps with multiple SDKs.
For a walkthrough of how to generate your object models based on server-side document schemas, see Generate SDK Object Models.
Once you have the generated object models, you can copy them directly into your client application and use them the same way you would any regular object or struct in your preferred programming language.
Define Data Access Patterns
Once you have decided on your app's data model, you can define a data access pattern and access rules for your app's data.
Client applications can query the queryable fields of a document to determine which objects to sync. Then, App Services applies rules and default roles to determine whether users can read or write the objects that match the query.
Define Data Access Rules
Data access rules determine which data to sync, as well as each user's ability to read and write data. Rules are closely linked to your app's data model.
With Flexible Sync, you specify which data to sync through queries for matching objects in a client application. App Services then evaluates roles and rules to determine which of those matching objects a user can read and write.
You can define roles on specific collections. Default roles provide read and write permissions when more specific roles do not apply. Default roles apply to all collections an App can access, but you can restrict a role to a specific collection by specifying the collection name.
Enable Sync
When you enable Sync, you specify how clients can access data in your App. For a walkthrough of how to turn on sync, refer to Configure and Enable Atlas Device Sync.
Optimize Sync Data Usage
Device Sync syncs all data from collections with a defined schema in your Atlas cluster. If you do not specify a field in your schema, Device Sync will not sync that field to the clients.
Sync stores some utility data in your synced cluster to help synchronize data with clients. Device Sync has optimizations built-in to reduce the amount of utility data stored in synced clusters. If you'd like to reduce the amount of utility data further to suit your use case, see our guide to Optimize Device Sync Atlas Usage.
Create Queries in Your Client Application
With Flexible Sync enabled, you can start creating queries from your client application.
The Realm SDKs provide methods to create, update, and remove queries from the client application. The SDKs use subscriptions to maintain those queries on the client side. Through these subscriptions, your applications sync objects with the backend app and can watch for and react to changes.
To create queries from your client application, refer to the Realm SDK documentation:
Important
Flexible Sync Ignores Custom Collation
Flexible Sync ignores any custom Collation that you may have configured on
a MongoDB collection in Atlas. Instead, Synced collections always use
{locale: "simple"} when evaluating Sync subscriptions or permissions.