Docs Menu

Docs HomeRealm

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.

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.

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}")

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")

To open a realm that synchronizes data with Atlas using Device Sync, refer to Open a Synced 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.

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 SDKDelete a Realm - Kotlin SDK →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.