Partition-Based Sync - Node.js SDK
On this page
Atlas Device Sync has two sync modes: Flexible Sync and Partition-Based Sync. We recommend using Flexible Sync. The information on this page is to support users who have existing apps that use Partition-Based Sync.
Note
Matching Sync Modes with Atlas Device Sync
When you use Atlas Device Sync in your client application, your implementation must match the Sync Mode you select in your backend App configuration. You can only use one Sync mode for your application. You cannot mix Partition-Based Sync and Flexible Sync within the same app.
Partition Value
When you select Partition-Based Sync for your backend App configuration, your client implementation must include a partition value. This is the value of the partition key field you select when you configure Partition-Based Sync.
The partition value determines which data the client application can access.
You pass in the partition value when you open a synced realm.
Open a Partition-Based Synced Realm
To open a realm with Partition-Based Sync, call Realm.open().
Pass in a Configuration
object, which must include the sync property defining a
SyncConfiguration object.
In the SyncConfiguration, you must include include user and partitionValue.
Important
Offline Login is Supported for Partition-Based Sync Configurations You can open a realm immediately with background sync or after a timeout elapses using Partition-Based Sync.
Open a Bundled Partition-Based Synced Realm
When opening a bundled synchronized realm that uses Partition-Based Sync, you must use the same partition key that was used in the original realm configuration. If you use a different partition key, the SDK throw an error when opening the bundled realm.
Migrate from Partition-Based Sync to Flexible Sync
You can migrate your App Services Device Sync Mode from Partition-Based Sync to Flexible Sync. Migrating is an automatic process that does not require any changes to your application code. Automatic migration requires Realm Node.js SDK version 11.10.0 or newer.
Migrating enables you to keep your existing App Services users and authentication configuration. Flexible Sync provides more versatile permissions configuration options and more granular data synchronization.
For more information about how to migrate your App Services App from Partition-Based Sync to Flexible Sync, refer to Migrate Device Sync Modes.
Updating Client Code After Migration
The automatic migration from Partition-Based Sync to Flexible Sync does not require any changes to your client code. However, to support this functionality, Realm automatically handles the differences between the two Sync Modes by:
Automatically creating Flexible Sync subscriptions for each object type where
partitionKey == partitionValue.Injecting a
partitionKeyfield into every object if one does not already exist. This is required for the automatic Flexible Sync subscription.
If you need to make updates to your client code after migration, consider updating your client codebase to remove hidden migration functionality. You might want update your client codebase when:
You add a new model or change a model in your client codebase
You add or change functionality that involves reading or writing Realm objects
You want to implement more fine-grained control over what data you sync
Make these changes to convert your Partition-Based Sync client code to use Flexible Sync:
Add
flexible:trueto your SyncConfiguration object where you open a synced realm.Add relevant properties to your object models to use in your Flexible Sync subscriptions. For example, you might add an
ownerIdproperty to enable a user to sync only their own data.Remove automatic Flexible Sync subscriptions and manually create the relevant subscriptions.
For examples of Flexible Sync permissions strategies, including examples of how to model data for these strategies, refer to Device Sync Permissions Guide.
Remove and Manually Create Subscriptions
When you migrate from Partition-Based Sync to Flexible Sync, Realm automatically creates hidden Flexible Sync subscriptions for your app. The next time you add or change subscriptions, we recommend that you:
This enables you to see all of your subscription logic together in your codebase for future iteration and debugging.
For more information about the automatically-generated Flexible Sync subscriptions, refer to Migrate Client App to Flexible Sync.