Open a Realm - Kotlin SDK

On this page

Open a Realm

Open a Local-Only Realm
Open an In-Memory Realm
Open a Synced Realm
Close a Realm
Copy Data into a New Realm

Note

Automatic Compaction of Realm File Size

New in version 1.6.0.

Realm automatically compacts files in the background by continuously reallocating data in the file and removing unused file space. Realm will automatically compact the file only when the file is not being accessed.

Open a Realm

Use RealmConfiguration to control the specifics of your realm that you would like to open.

When you open the realm, you must provide a list of object schemas as an argument.

A realm schema is a list of valid object schemas that a realm may contain. Every Realm object must conform to an object type that's included in its realm's schema.

If a realm already contains data when you open it, Realm Database validates each object to ensure that an object schema was provided for its type and that it meets all of the constraints specified in the schema.

Open a Local-Only Realm

To open a realm that only persists data locally, create a RealmConfiguration with RealmConfiguration.Builder and pass the resulting RealmConfiguration to Realm.open():

val config = RealmConfiguration.Builder(setOf(Frog::class))
    .build()
val realm = Realm.open(config)
Log.v("Successfully opened realm: ${realm.configuration.name}")

Open an In-Memory Realm

To open a realm that runs entirely in memory without being written to a file, create a RealmConfiguration using the inMemory property with RealmConfiguration.Builder. Then pass the resulting RealmConfiguration to Realm.open():

val config = RealmConfiguration.Builder(setOf(Frog::class))
    .inMemory()
    .build()
val realm = Realm.open(config)
Log.v("Successfully opened an in memory realm")

Open a Synced Realm

To open a realm that synchronizes data with Atlas using Device Sync, refer to Open a Synced Realm.

Close a Realm

You close a realm with realm.close(). The close() method blocks until all write transactions on the realm have completed.

realm.close()

Warning

It's important to close your realm instance to free resources. Failing to close realms can lead to an OutOfMemoryError.

Copy Data into a New Realm

To copy data from an existing realm to a new realm with different configuration options, pass the new configuration to the Realm.writeCopyTo() method. For example, you might copy data as a way to backup a local realm or to convert a synced realm to a local realm.

You can copy data to a realm that uses the same configuration:

Local realm to local realm
In-memory realm to in-memory realm
Synced realm to synced realm

You can copy data to a realm that uses different sync configurations:

Local realm to Partition-Based Sync realm
Synced realm to local realm

Warning

You cannot copy data from a local realm to a Flexible Sync realm.

You can also combine changes to the configuration. For example, you can copy data from an unencrypted, in-memory synced realm to an encrypted local realm.

Some additional considerations to keep in mind while using Realm.writeCopyTo():

The destination file cannot already exist.
Copying a realm is not allowed within a write transaction or during a migration.
When using Device Sync, you must sync all local changes with the server before the copy is written. This ensures that the file can be used as a starting point for a newly installed application. Realm throws an error if there are pending uploads.
You can use uploadAllLocalChanges() and downloadAllServerChanges() to ensure all sync processes are completed.

Example

Copy Data from Flexible Sync Realm to Local Realm

// Instantiate the synced realm with your App ID
val app = App.create(YOUR_APP_ID)
runBlocking {
    val user = app.login(Credentials.anonymous())
    // Create the synced realm configuration
    val syncConfig = SyncConfiguration.Builder(user, setOf(Toad::class))
        .initialSubscriptions { realm ->
            add(
                realm.query<Toad>("name == $0", "name value"),
                "subscription name"
            )
        }
        .build()
    // Open the synced realm and add data to it
    val syncRealm = Realm.open(syncConfig)
    Log.v("Successfully opened realm: ${syncRealm.configuration}")
    syncRealm.write {
        this.copyToRealm(Toad().apply {
            name = "Kermit"
        })
    }
    // Wait for write to sync
    syncRealm.syncSession.uploadAllLocalChanges(30.seconds)
    // Create the local realm
    val localConfig = RealmConfiguration.Builder(setOf(Toad::class))
        .name("local.realm")
        .build()
    // Copy data from synced realm to the new realm
    syncRealm.writeCopyTo(localConfig)
    // Close the synced realm when you're done copying
    syncRealm.close()
    // Open the new local realm
    val localRealm = Realm.open(localConfig)
    // Copied Toad object is available in the new realm
    val toad: Toad =
        localRealm.query<Toad>().find().first()
    Log.v("Copied Toad: ${toad.name}")
    localRealm.close()
}

You can also include a new encryption key in the copied realm's configuration or remove the encryption key from the new configuration.

Example

Copy Data from Unencrypted to Encrypted Realm

runBlocking {
    // Create the unencrypted realm
    val unencryptedConfig = RealmConfiguration.Builder(setOf(Toad::class))
        .name("unencrypted.realm")
        .build()
    // Open the realm and add data to it
    val unencryptedRealm = Realm.open(unencryptedConfig)
    unencryptedRealm.write {
        this.copyToRealm(Toad().apply {
            name = "Kermit"
        })
    }
    // ... Generate encryption key ...
    // Create the encrypted realm
    val encryptedConfig = RealmConfiguration.Builder(setOf(Toad::class))
        .name("encrypted.realm")
        .encryptionKey(getEncryptionKey())
        .build()
    // Copy data from `unencryptedRealm` to the new realm
    // Data is encrypted as part of the copy process
    unencryptedRealm.writeCopyTo(encryptedConfig)
    // Close the original realm when you're done copying
    unencryptedRealm.close()
    // Open the new encrypted realm
    val encryptedRealm = Realm.open(encryptedConfig)
    // Copied Toad object is available in the new realm
    val toad: Toad =
        encryptedRealm.query<Toad>().find().first()
    Log.v("Copied Toad: ${toad.name}")
    encryptedRealm.close()
}

Example

Copy Data from In-Memory to Local Realm

runBlocking {
    // Create the in-memory realm
    val inMemoryConfig = RealmConfiguration.Builder(setOf(Toad::class))
        .name("inMemory.realm")
        .inMemory()
        .build()
    // Open the realm and add data to it
    val inMemoryRealm = Realm.open(inMemoryConfig)
    inMemoryRealm.write {
        this.copyToRealm(Toad().apply {
            name = "Kermit"
        })
    }
    // Create the local realm
    val localConfig = RealmConfiguration.Builder(setOf(Toad::class))
        .name("local.realm")
        .build()
    // Copy data from `inMemoryRealm` to the new realm
    inMemoryRealm.writeCopyTo(localConfig)
    // Close the original realm when you're done copying
    inMemoryRealm.close()
    // Open the new local realm
    val localRealm = Realm.open(localConfig)
    // Copied Toad object is available in the new realm
    val toad: Toad =
        localRealm.query<Toad>().find().first()
    Log.v("Copied Toad: ${toad.name}")
    localRealm.close()
}

← Manage Realm Database Files - Kotlin SDK Delete a Realm - Kotlin SDK →