Open a Realm - Kotlin SDK
On this page
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() }