Docs Menu

Open & Close a Realm - Android SDK

On this page

Interacting with realms in an Android application uses the following high-level series of steps:

  1. Create a configuration for the realm you want to open.
  2. Open the realm using the config.
  3. Close the realm to free up resources when you're finished.

You can save any RealmConfiguration or SyncConfiguration as the default for your application using the setDefaultConfiguration() method:

You can then use getDefaultConfiguration() to access that configuration, or getDefaultInstance() to open a realm with that configuration:

Local realms store data only on the client device. You can customize the settings for a local realm with RealmConfiguration.

To configure settings for a realm, create a RealmConfiguration with a RealmConfiguration.Builder. The following example configures a local realm with:

  • the file name "alternate-realm"
  • synchronous reads explicitly allowed on the UI thread
  • synchronous writes explicitly allowed on the UI thread
  • automatic compaction when launching the realm to save file space
Important
Synchronous Reads and Writes on the UI Thread

By default, you can only read or write to a realm in your application's UI thread using asynchronous transactions. That is, you can only use Realm methods whose name ends with the word Async in the main thread of your Android application unless you explicitly allow the use of synchronous methods.

This restriction exists for the benefit of your application users: performing read and write operations on the UI thread can lead to unresponsive or slow UI interactions, so it's usually best to handle these operations either asynchronously or in a background thread. However, if your application requires the use of synchronous realm reads or writes on the UI thread, you can explicitly allow the use of synchronous methods with the following SyncConfiguration options:

Tip

To open a realm, create a RealmConfiguration with RealmConfiguration.Builder and pass the resulting RealmConfiguration to getInstance() or getInstanceAsync():

Use the readOnly() method when configuring your realm to make it read-only:

To create a realm that runs entirely in memory without being written to a file, use the inMemory() method when configuring your realm:

To open a Dynamic Realm with a mutable schema, use DynamicRealm:

Synced realms use Realm Sync to store data both on the client device and in your synced data source. Opening a synced realm works exactly like opening a local realm, except you use SyncConfiguration to customize the settings for synced realms.

To configure settings for a realm, create a SyncConfiguration with a SyncConfiguration.Builder. The following example configures a synced realm with:

  • synchronous reads explicitly allowed on the UI thread
  • synchronous writes explicitly allowed on the UI thread
  • explicit waiting for all backend changes to synchronize to the device before returning an open realm
  • automatic compaction when launching the realm to save file space
Important
Synchronous Reads and Writes on the UI Thread

By default, you can only read or write to a realm in your application's UI thread using asynchronous transactions. That is, you can only use Realm methods whose name ends with the word Async in the main thread of your Android application unless you explicitly allow the use of synchronous methods.

This restriction exists for the benefit of your application users: performing read and write operations on the UI thread can lead to unresponsive or slow UI interactions, so it's usually best to handle these operations either asynchronously or in a background thread. However, if your application requires the use of synchronous realm reads or writes on the UI thread, you can explicitly allow the use of synchronous methods with the following SyncConfiguration options:

To open a synced realm, call getInstanceAsync(), passing in a SyncConfiguration object. The following code demonstrates how to create a realm with specific sync settings created using a SyncConfiguration object:

The code above shows how to open the realm asynchronously by using getInstanceAsync(). You can also open a realm synchronously by using getInstance(), which returns an open realm before synchronizing all data from the backend. However, this may lead to temporary data inconsistencies while the remote data is downloaded, and is generally not recommended. You can use the waitForInitialRemoteData() configuration option to force the SDK to fetch remote data before opening the realm to avoid these inconsistencies.

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.

You can open a synced realm when offline with the exact same syntax that you use to open a synced realm while online. Not all SDKs follow this pattern, so cross-platform developers should consult the documentation for each SDK to learn more.

It is important to remember to call the close() method when done with a realm instance to free resources. Neglecting to close realms can lead to an OutOfMemoryError.

Realm modules are collections of Realm object models. Specify a module or modules when opening a realm to control which classes Realm Database should include in your schema. If you do not specify a module, Realm uses the default module, which includes all Realm objects defined in your application.

Note

Libraries that include Realm Database must expose and use their schema through a module. Doing so prevents the library from generating the default RealmModule, which would conflict with the default RealmModule used by any app that includes the library. Apps using the library access library classes through the module.

Give Feedback
© 2021 MongoDB, Inc.

About

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