Sync Changes Between Devices - iOS SDK

On this page

The typical flow for opening a synced realm for the first time involves:

  1. Authenticating the user
  2. Creating a sync configuration
  3. Opening the user's synced realm with the configuration.

At authentication, we cache user credentials in a sync_metadata.realm file on device.

When you open a synced realm after authenticating, you can bypass the login flow and go directly to opening the synced realm, using the same sync configuration you already created.

With cached credentials, you can:

  • Open a synced realm immediately with the data that is on the device. You can use this method offline or online.
  • Open a synced realm after syncing changes with your Realm app. You can only use this method if the user is online.

You can work with synced realms offline if the user credentials are cached and you use Realm initializers to open the realms. If your app requires that a user always have the most up-to-date data, you'll use asyncOpen to open the realm, but that requires a user to have a network connection.

Synced realms differ from local Realm Database in a few ways:

  • Synced realms attempt to sync changes with your backend Realm app, whereas local realms do not.
  • Synced realms can be accessed by authenticated users, while local realms do not require any concept of users or authentication.
  • Some methods of opening synced realms require users to be online, while local realms can be used entirely offline.

You can copy data from a local Realm Database to a synced realm, but you cannot sync a local Realm Database. You must initialize a synced realm with a sync configuration.

The first time a user opens a realm, you'll need to authenticate the user. Upon this initial login, we cache login credentials. On subsequent opens, you can check for a logged-in user, and then open new realms. You don't need to complete the login flow while you have a logged-in user.

Depending on your business logic, you may also require the user to download data from MongoDB Realm before opening a synced realm on device.

After you have authenticated a user and created a sync configuration to open a realm, you can open the same realm again using the sync configuration with cached credentials. You can use two different methods to open the synced realm, depending on your needs:

  • Open a synced realm with data that is on the device immediately. This works regardless of network status, and enables the user to start working with the realm without waiting for changes to download from the server. However, data that is on the device may be stale. Additionally, this may result in behavior that seems unexpected or surprising to the user. Data may appear "suddenly" as it syncs in the background after the user has already begun working with the realm. You'll need to account for this in your UI logic.
  • Open a synced realm after syncing changes. This requires the user to have a network connection, so you should check the network connection before attempting to open the realm from the server. This method of opening the realm ensures that the user always has the most up-to-date data from the server. The cost of using this method is an upfront pause while loading, and being unable to open the realm offline.

You can use initializers to open the realm immediately, using the data that is on the device. If you want to open a synced realm offline, use this method. You must have a cached, logged-in user.


Consider the example of a note-taking app. You might decide it's most important for your user to be able to quickly jot down a note. The user shouldn't have to wait while downloading changes that a family member made to a shared note. In this case, opening a realm with init gets the user to the UI right away, or while the user is offline. When the user has a network connection, changes will sync in the background.

In contrast, you might want a store inventory app to always check the server for changes before working with a realm. If you use stale data from the last time the realm was open on the device, the app data could reflect incorrect counts, inaccurate pricing data, or other out-of-date data issues. In that case, you'd want the app to download changes before letting the user work with the data.


A synced realm is not interchangeable with a local Realm Database. If you want to sync a local Realm Database, you'll need to copy the content from the local realm to a synced realm. A local realm lives only on the device and never attempts to sync with the server. A synced realm contains additional Sync-related metadata, and consistently and persistently attempts to connect and sync data with the server.

In some apps, such as games, you might want the user to always have current data. Use asyncOpen to sync the realm with the Realm app before opening it.


Say a user plays a game on both an iPad and an iPhone. The user progresses three levels on the iPad. Later, the user opens the game on an iPhone. In this case, asyncOpen is a better way to open the realm. Loading with stale data would get the user into the game faster, but the user's data would be three levels out of sync.

In contrast, if you had an app that allowed the user to record and save their favorite recipes, you might want to give them the option to create a new recipe without waiting to download updates, or even if they're offline. If you opened a synced realm with data on the device, the user could enter a new recipe, which would sync with the Realm app when they next had a network connection.

A common pattern is to open a realm with asyncOpen in the login flow, and then use init for subsequent opens. If you want users to only interact with the most up-to-date version of your data, you can exclusively use asyncOpen. This incurs the cost of additional loading time and prevents users from opening a realm while offline.

If you want your app to update data in the background (while the app is minimized), iOS requires you to implement Background App Refresh. Enabling Background App Refresh minimizes the time it takes for the user to see the most recent data; without Background App Refresh, MongoDB Realm updates the data when the user launches the app, potentially resulting in noticeable lag.

To use the realm while the device is locked, you must adjust the file protection settings. See Use Realm When the Device Is Locked.


MongoDB Realm's offline-first design means that you generally don't need to check the current network connection state. That said, the connectionState property is available if your app calls for some indication of connection state.

While developing an application that uses Realm Sync, you should set an error handler. This error handler will detect and respond to any failed sync-related API calls.

In some cases, you may want to completely delete a realm file from disk.

Realm avoids copying data into memory except when absolutely required. As a result, all objects managed by a realm have references to the file on disk. Before you can safely delete the file, you must ensure the deallocation of these objects:

  • All objects read from or added to the realm
  • All List and Results objects
  • All ThreadSafeReference objects
  • The realm itself

In practice, there are two safe times to delete the realm file:

  1. On application startup before ever opening the realm.
  2. After only having opened the realm within an explicit autorelease pool, which ensures deallocation of all of objects within it.

To perform a client reset, see Client Resets - iOS SDK.


See RLMSyncLogLevel for a description of each available log level. Note that more logging can negatively affect performance.


To diagnose and troubleshoot errors while developing your application, set the log level to debug or trace. For production deployments, decrease the log level for improved performance.

Give Feedback

On this page