Docs Menu

Sync Changes Between Devices - Swift SDK

On this page

Before you can access a synced realm from the client, you must:

  1. Enable sync in the Atlas App Services UI.
  2. Initialize the app
  3. Authenticate a user in your client project.
  4. Open a Synced Realm

The syntax to read, write, and watch for changes on a synced realm is identical to the syntax for non-synced realms. While you work with local data, a background thread efficiently integrates, uploads, and downloads changesets.

When Using Sync, Avoid Writes on the Main Thread

The fact that Realm performs sync integrations on a background thread means that if you write to your realm on the main thread, there's a small chance your UI could appear to hang as it waits for the background sync thread to finish a write transaction. Therefore, it's a best practice not to write on the main thread when using Atlas Device Sync.

The following code creates a new Task object and writes it to the realm:

let task = QsTask(name: "Do laundry")
try! realm.write {
See also:

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, 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.


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 Atlas Device 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.

←  Link User Identities - Swift SDKFlexible Sync - Swift SDK →
Give Feedback
© 2022 MongoDB, Inc.


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