Migrate Device Sync Modes
On this page
Atlas App Services Apps can have one of two Device Sync modes: Partition-Based Sync and Flexible Sync. Partition-Based Sync is an older mode and you should consider migrating to Flexible Sync.
Migrating an App Services App that uses Partition-Based Sync to Flexible Sync is an automatic process. Other than upgrading the SDK version, migrating Sync modes doesn't require any changes to your client app code.
Migration results in Partition-Based Sync clients communicating with a Flexible Sync backend. We recommend eventually migrating your client app code to also use Flexible Sync instead of Partition-Based Sync.
Requirements
App Services App:
Currently use Partition-Based Sync
Linked Atlas Cluster:
Use MongoDB 5.0 or later for Flexible Sync compatibility
Enable storage auto-scaling
Be an M10+ Cluster Tier
Have time-based oplog setting enabled
Client apps:
Minimum Atlas Device SDK version:
Swift SDK v10.40.0 or later
Kotlin SDK v1.9.0 or later
Node.js SDK v11.10.0 or later
React Native SDK v11.10.0 or later
.NET SDK v11.1.0 or later
Java SDK v10.16.0 or later
Have a Client Reset Handler configured.
What to Know Before Migrating
Migrating your App's Sync mode involves changes that affect both client apps and your App's backend. You should be aware of the effects and plan ahead.
Client apps that don't meet the minimum SDK version requirement will not be able to sync after migration.
How long a migration takes is directly proportional to the amount of data that needs to be migrated. The more data, the longer it will take to migrate.
Migrations can be canceled during the migration or reverted within a certain timeframe after the migration is finished.
Progress notifications will not work after migration because Flexible Sync does not support them.
Client apps that were connected to the Partition-Based Sync backend will experience a client reset after the backend is migrated to Flexible Sync. You should use a client reset handler with recovery enabled so you don't lose any pending changes from before the client reset.
Creating new tables in a migrated Flexible Sync backend using Development Mode from a Partition-Based Sync client may lead to unexpected behavior.
Migration Stages
You can see your migration's stage in the App Services UI. There are three stages to a Sync mode migration:
Syncing Partition-Based Sync metadata
At this stage, client apps can connect to your App's backend, but local writes will not sync. These writes will be lost if you don't have a client reset handler to recover unsynced changes.
Clients will receive updates to synced collections, but won't be able to send uploads or receive upload acknowledgements.
Building Flexible Sync metadata
Clients cannot connect at this stage. The duration of this stage is directly proportional to the amount of data in synced collections.
Completed migration
Manage Sync Migration appears on the Device Sync page if the migration hasn't been committed or reverted.
After the migration has finished, check out the After Migration section for more information about how Partition-Based Sync clients interact with the Flexible Sync backend.
Migrate Partition-Based Sync to Flexible Sync
After beginning migration from Partition-Based Sync to Flexible Sync, the process is mostly automatic. However, you can control important parts of the migration.
During a migration, you can cancel it. After a migration, you can revert it or manually commit the migration.
Begin Migration
Before you begin a migration, make sure you're aware of the migration stages and effects.
Migration generally has similar effects as terminating and re-enabling Device Sync. There are some additional effects of migration:
In the App Services UI, all configuration pages will be read-only. For example, Rules, Schemas, Functions, and Triggers screens.
Your App will experience a period of read-only Sync and then a period of downtime.
The new Flexible Sync configuration will set client max offline time to 30 days.
Storage in your Atlas cluster used by Device Sync metadata is temporarily doubled. Partition-Based Sync metadata and Flexible Sync metadata must temporarily co-exist. Depending on the size of your synced data, this could affect billing every time you migrate. The duplicated metadata is removed after the migration is rolled back or committed.
To migrate from Partition-Based Sync to Flexible Sync:
Navigate to the Device Sync screen:
From the App Services UI, click Device Sync in the left navigation menu. The Dashboard tab displays by default.
Select the Configuration tab.
Click Start migration.
![Begin a migration]()
click to enlargeReview the information for the migration process, then click Next: Migration Requirements.
Ensure you meet the migration requirements, then click Start Migration.
Note
Temporary Sync Disruption
Clients will not be able to sync their local writes until the migration has completed.
After a migration is completed, Partition-Based Sync client apps will go through a client reset. Then, they can communicate with your App's Flexible Sync backend. You can disable and re-enable Flexible Sync and client apps will still communicate with your backend.
If you re-enable Partition-Based Sync you will lose the "migrated" status. This means you'll need to do another migration if you want to use Flexible Sync on the backend with Partition-Based Sync client apps.
Migrate Permissions and Rules
Your App's permissions and rules will be automatically migrated if the Partition-Based Sync rules have direct App Services Rules equivalents. This will override previously-defined App Services Rules.
In step 4 above, you will see if your permissions and rules can be automatically migrated. On the Review Migration Process step in the App Services UI, look for Rules & Permissions.
Some Partition-Based Sync rule strategies can't translate directly to App Services Rules. You may need to manually migrate permissions that include:
%functionoperator.Function rules are not compatible with Flexible Sync and cannot be migrated.
%or,%not,%nor,%andexpansions.These permissions may work, but there is enough nuance that you should test them to ensure expected behavior. Testing new permissions won't work on the App you are migrating. Instead, create a new Flexible Sync app to test your manually-migrated permissions. Then apply the tested permissions to the app you are migrating.
See the list of Flexible Sync-compatible expansions for all supported expansions.
You should also check out the Device Sync Permissions Guide for more information about how to work with permissions.
Cancel Migration
You can cancel a migration at any time while it is in progress. This will return your App the Partition-Based Sync, with all settings as they were before the migration started.
If you cancel a migration, you need to start over from the beginning with future migration attempts.
To cancel a migration:
Navigate to Device Sync screen:
From the App Services UI, click Device Sync in the left navigation menu. The Dashboard tab displays by default.
Select the Configuration tab.
In the notification banner, click Cancel Migration.
![Cancel a migration]()
click to enlargeThis will cancel your migration. You will need to migrate again if you want to enable Flexible Sync in the future.
Commit Migration
After your migration has completed, it is in an evaluation state. You can manually commit the migration to make it permanent or revert the migration to return your App to Partition-Based Sync.
If you don't commit or revert the migration, it will automatically commit according to your minimum oplog window. For example, if your minimum oplog window is 48 hours, you will have 48 hours to revert your migration.
After a migration is committed, the old Partition-Based Sync metadata is deleted and you cannot revert the migration.
To manually commit a migration:
Navigate to Device Sync screen:
From the App Services UI, click Device Sync in the left navigation menu. The Dashboard tab displays by default.
Select the Configuration tab.
At the top of the page, click the Manage migration dropdown, then select Delete Partition-Based Sync metadata.
![Commit a migration]()
Confirm that you want to delete your metadata and commit to the migration to Flexible Sync.
Important
Once deleted, you cannot recover your Partition-Based Sync metadata.
Revert Migration
You can revert a migration after it has completed and before it has been committed.
Completed migrations are automatically committed in accordance with your minimum oplog window. You can increase or decrease the amount of time you have to revert a migration by adjusting the minimum oplog window.
You cannot revert a migration that has been committed.
Similar to canceling a migration, if you revert a migration, you need to start over from the beginning with future migration attempts.
To revert a migration:
Navigate to Device Sync screen:
From the App Services UI, click Device Sync in the left navigation menu. The Dashboard tab displays by default.
Select the Configuration tab.
From the Manage Sync section, click the Manage migration dropdown, then select Revert back to Partition-Based Sync.
![Revert a migration]()
This will revert your migration. You must migrate again if you want to enable Flexible Sync in the future.
After Backend Migration
Your migrated backend uses a partition key field in your object models to map the Partition-Based Sync client objects to Flexible Sync equivalents on the backend. If your object models don't have a partition key field, the backend automatically injects one into every object the Partition-Based Sync client creates.
These are some other characteristics of the injected field you should be aware of:
The injected field follows this structure:
<yourPartitionKey> == <yourPartitionValue>. The field key is derived from your old Partition-Based Sync backend configuration. The value is derived from your current Partition-Based Sync client configuration.The injected field does not sync back to the client that created the object. This means the originating client won't be able to read the injected
partitionKeyfield.
The Partition-Based Sync client automatically creates sync subscriptions for
each table where partitionKey == partitionValue. This will continue
until you migrate your client app to
Flexible Sync.
After migrating your client app to Flexible Sync, the backend will stop injecting the partition key field. If your client app relies on the partition key field for managing sync subscriptions, you should add the partition key field to your object models.
If you don't, objects created in new versions of your app will not be synced to clients using older versions of your client app code.
Migrate Client App to Flexible Sync
After your App's backend has been migrated to Flexible Sync, we recommend that you migrate your client app to Flexible Sync. When you migrate your client app to Flexible Sync, the client will stop automatically creating sync subscriptions for each object model in your app's data model.
We also recommend removing all sync subscriptions and then creating new subscriptions for your data. This is the clearest way to control what data is synced after a migration.
If you want to remove individual subscriptions, the automatically
generated subscriptions use a specific naming format: flx_migrated_ + your
object model's name. For example, a Person object model's subscription
name would be flx_migrated_Person.
You can keep the automatically-generated subscriptions if you don't want to remove and recreate them. But because these subscriptions aren't created in your client code, they may make it harder for you to maintain and extend client code.
For more information about updating client code after migrating from Partition-Based Sync to Flexible Sync, refer to: