Sync Changes Between Devices - Swift SDK
On this page
Prerequisites
Before you can access a synced realm from the client, you must:
- Enable sync in the Atlas App Services UI.
- Initialize the app
- Authenticate a user in your client project.
- Open a Synced Realm
Sync Data
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.
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 { realm.add(task) }
Sync Changes in the Background
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.
Suspend or Resume a Sync Session
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.
Check Upload & Download Progress for a Sync Session
Check the Network Connection
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.
Handle Sync Errors
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.
Delete a Client Realm File
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:
- On application startup before ever opening the realm.
- After only having opened the realm within an explicit
autoreleasepool, which ensures deallocation of all of objects within it.
To perform a client reset, see Client Resets - Swift SDK.
Set the Client Log Level
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.