Docs Menu

Sync Changes Between Devices - Swift SDKicons/link.png

On this page

The typical flow for opening a synced realm 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 downloading changes from your Realm app. This requires the user to have an active internet 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.
  • With synced realms, you can specify the download behavior to download updates before opening a realm. However, this requires users to be online. Local realms - with no sync capability - can always be used 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.

New in version 10.15.0.

When you open a synced realm with the Swift SDK, you can pass the downloadBeforeOpen parameter to specify whether to download the changeset from your Realm app before opening the realm. This parameter accepts a case from the OpenBehavior enum:

  • never: Immediately open the realm on the device. Download changes in the background when the user has internet, but don't block opening the realm.
  • always: Check for changes every time you open the realm. Requires the user to have an active internet connection.
  • once: Download data before opening a realm for the first time, but open it without downloading changes on subsequent opens. This lets you populate a realm with initial data, but enables offline-first functionality on subsequent opens.
func testSpecifyDownloadBehavior() async throws {
let app = App(id: YOUR_REALM_APP_ID)
let user = try await app.login(credentials: Credentials.anonymous)
let partitionValue = "some partition value"
var configuration = user.configuration(partitionValue: partitionValue)
let realm = try await Realm(configuration: configuration, downloadBeforeOpen: .always)
print("Successfully opened realm after downloading: \(realm)")

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.

Opening a synced realm starts a SyncSession for that realm. You can suspend and resume the sync session on the realm. Pausing a sync session only suspends that realm's sync session. If you have more than one open realm, suspend does not affect the sync sessions for other realms.


Use the .suspend() method to control when a device syncs. You should only use it for temporary and short-term pauses of syncing.

Examples of when to use .suspend() include:

  • Syncing data only at specified time of day
  • Conserving device battery use

Don't use the .suspend() method to stop syncing for indefinite time periods or time ranges in months and years. The functionality is not designed or tested for these use cases, and you could encounter a range of issues when using it this way.


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 - Swift 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
MongoDB logo
© 2021 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.