Get Started with Atlas Device Sync
On this page
To sync data across devices, enable Device Sync, then use the sync-related methods and properties in the Atlas Device SDK.
Tip
Check out the tutorial
If you prefer to learn by example, check out the Device Sync tutorial, which uses 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.
Device Sync requires an Atlas cluster running 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 Services App linked to your Atlas cluster.
Configure Your Data Model
Choose an SDK
Atlas Device SDK wraps Realm Core Database, an object database optimized for mobile. The SDK, available for multiple languages and platforms, includes everything you need to work with synced databases in your client code. You can use multiple SDK languages to work with the same set of synced data across devices and platforms.
This guide focuses on configuring Device Sync with the SDK. For in-depth documentation that includes details on how to install and use the Atlas Device SDK more generally, check out the SDK docs:
Note
Using Device Sync with the Realm JS WebAssembly SDK
For more information on building realtime web apps for the browser with the Realm Database API and Atlas Device Sync, check out Get Started with Realm Web & Atlas Device Sync (Preview). Or you can query the same data in an Atlas cluster using MongoDB Data Access.
Define Data Model
A synced database uses object models that you define to determine the type of objects in the database. Additionally, Sync requires a server-side document schema for each synced object type so the server can translate and apply changes between synced databases 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, you can automatically generate 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.
To get started, check out Create a Data Model.
Generate object models from a document schema: If you already have data in Atlas, you can automatically generate language-specific object models that 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 or plan to build apps with multiple SDKs.
For a walkthrough of how to generate object models that you can use in your client applications, 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 Device 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.
Configure Sync
Device Sync lets you specify how clients can access data in your App. For a walkthrough of how to enable and configure 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 Device Sync enabled, you can start creating queries from your client application.
The Atlas Device SDK 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 Atlas Device SDK documentation in your preferred programming language:
Warning
Query Size Limit
The size limit for queries from your client application when using Device Sync is 256 kB. Exceeding this limit in a query results in a LimitsExceeded Error.
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.