Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Open & Close a Realm - Java SDK

On this page

  • The Default Realm
  • Local Realms
  • Local Realm Configuration
  • Open a Local Realm
  • Read-Only Realms
  • In-Memory Realms
  • Dynamic Realms
  • Close a Realm
  • Configure Which Classes to Include in Your Realm Schema

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


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 realm, create a RealmConfiguration with RealmConfiguration.Builder and pass the resulting RealmConfiguration to getInstance() or getInstanceAsync():

It's sometimes useful to ship a prepared realm file with your app that contains shared data that does not frequently change. You can use the readOnly() method when configuring your realm to make it read-only. This can prevent accidental writes to the realm and causes the realm to throw an IllegalStateException if a write occurs.


Read-Only Realm Files are Writeable

Read-only realms are only enforced as read-only in process. The realm file itself is still writeable.

You can create a realm that runs entirely in memory without being written to a file. When memory runs low on an Android device, in-memory realms may swap temporarily from main memory to disk space. The SDK deletes all files created by an in-memory realm when:

  • the realm closes

  • all references to that realm fall out of scope

To create an in-memory realm, use inMemory() when configuring your realm:

Conventional realms define a schema using RealmObject subclasses or the RealmModel interface. A DynamicRealm uses strings to define a schema at runtime. Opening a dynamic realm uses the same configuration as a conventional realm, but dynamic realms ignore all configured schema, migration, and schema versions.

Dynamic realms offer flexibility at the expense of type safety and performance. As a result, only use dynamic realms when that flexibility is required, such as during migrations, manual client resets, and when working with string-based data like CSV files or JSON.

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

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


Libraries that include Realm 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.

← Realm Files