Sync Data¶
Realm Sync is currently in Beta.
Prerequisites¶
Before you can access a synced realm from the client, you must:
- Enable sync in the Realm UI.
- Initialize the app and authenticate a user in your client project.
Open a Synced Realm¶
To open a synced realm for a given partition value, initialize a
Realm
with the Realm.getInstanceAsync()
method.
val user: User? = app.currentUser() val partitionValue: String = "myPartition" val config = SyncConfiguration.Builder(user!!, partitionValue) .build() var realm: Realm // Sync all realm changes via a new instance, and when that instance has been successfully created connect it to an on-screen list (a recycler view) Realm.getInstanceAsync(config, object: Realm.Callback() { override fun onSuccess(_realm: Realm) { // since this realm should live exactly as long as this activity, assign the realm to a member variable realm = _realm } })
The partition value specifies which subset of your data to sync. This is typically a user ID, project ID, store ID, or some other category identifier in your app that has particular relevance to the current user.
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 never to write on the main thread when using Realm Sync.
The following code reads a collection of Task
objects, then writes a
new Task
to the realm:
// Read all tasks in the realm. No special syntax required for synced realms. val tasks : RealmResults<Task>? = realm.where<Task>().findAll() // Write to the realm. No special syntax required for synced realms. realm.executeTransaction { realm.insert(Task()) } // Don't forget to close your realm! realm.close()
Summary¶
- Open a synced realm with the configuration object generated when you pass a partition value to the user object's
SyncConfiguration
Builder. - Compared to using a non-synced realm, there is no special syntax for reading from, writing to, or watching objects on a synced realm.
- You should avoid writing to a synced realm on the main thread.