On this page
Some SDKs support an easier implementation for adding sync to a local-only realm than the steps outlined on this page.
If you have a mobile app that uses a local Realm Database and you want to convert the app to use Realm Sync, there are a few steps you need to follow. You first need to set up a Realm backend, and then you make code changes in your client app(s).
In the following sections, you will learn to do the following on the backend:
- Create a new realm app in MongoDB Atlas,
- Configure at least one User Authentication provider, and
- Choose a partition strategy.
And then, in your client app, you will:
- Update your Realm object models,
- Connect to the new synced realm with a sync configuration file,
- Authenticate the user.
Finally, if needed, you will also need to copy your local data to the new synced realm.
To sync your data between devices and with MongoDB Atlas, you first need to create a Realm app. This app serves -- at a minimum -- two purposes: it provides a gateway to the data, and it provides data security in the form of user authentication, data encryption, and access control.
To get started creating the backend app, follow the steps in Create a Realm App with Realm UI.
User authentication plays a crucial role in Realm Sync. Realm provides many different Authentication Providers such as email/password and OAuth; once you have configured one or more providers, you can then control exactly who has access to which data.
To set up an auth provider, choose one of the authentication providers and follow the configuration steps for the provider(s) of your choice.
Data partitions let you configure which users have access to which data. This process is often the most time-consuming part of setting up Realm Sync, as you as you consider what partition strategy is the best fit for your use case and data.
As part of determining your partition strategy, you'll choose a partition key. You might choose a partition key that is already a part of your object models, which you can then specify when you set up Realm Sync. If you have chosen a partition key that isn't already a part of your object models, you'll need to update those models.
Now that you have the backend set up for Sync, you need to make a few changes in your client app. Follow the steps in the Quick Start for your language/platform:
None of the data in your local realm will be automatically transferred to your new synced realm; it is up to you to ensure the data you want to preserve is copied to the new realm. How you go about doing this depends, in part, on your specific needs, but the following diagram and steps outline the process for copying all of the data from the local realm to the synced realm. If done correctly, the impact on app performance after the initial copy will be minimal.
- Check if a synced realm already exists.
- If not, create one. Open a connection to it and to the local realm.
- Read each record from the local realm and modify it to meet the needs of the synced realm (adding a partition key, for example).
- Copy the modified record to the new synced realm. Sync will automatically copy the record to Atlas.
- Confirm that all records you want to preserve are in the new realm.
- Delete the local realm file.
- On each subsequent app load, simply check if the local realm has been deleted.