Configure & Open a Realm - Kotlin SDK

Realm Files

Realm stores a binary-encoded version of every object and type in a realm in a single .realm file. When you open a realm, Realm creates the .realm file if it doesn't already exist. The file is located at a specific path, which you can define when you open the realm. Realm also creates additional auxiliary files for each realm, such as lock and management files. To learn more about these files, refer to Database Internals - Kotlin SDK. Note that deleting these files has important implications. For more information about deleting .realm or auxiliary files, refer to Delete a Realm.

If you don't want to create a .realm file or its associated auxiliary files, you can open an in-memory realm. Refer to the Open an In-Memory Realm section for more information.

Open a Realm

To open a realm, create a RealmConfiguration object that defines the details of a realm. Then, pass the resulting RealmConfiguration to Realm.open().

You can open a realm with default configuration values or you can build a RealmConfiguration with additional configuration options. However, you must pass a schema parameter that includes all object classes that you want to use in the realm.

After you open the realm with the desired configuration, you can read and write data based on your defined schema.

The examples on this page refer to the following Realm objects:

class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
}
class Person : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
}

// Creates a realm with default configuration values
val config = RealmConfiguration.create(
    // Pass object classes for the realm schema
    schema = setOf(Frog::class, Person::class)
)
// Open the realm with the configuration object
val realm = Realm.open(config)
Log.v("Successfully opened realm: ${realm.configuration.name}")
// ... use the open realm ...

// Create the in-memory realm configuration
val config = RealmConfiguration.Builder(
    schema = setOf(Frog::class, Person::class)
)
    .inMemory()
    .build()
// Open the realm with the configuration object
val realm = Realm.open(config)
Log.v("Successfully opened an in-memory realm")
// ... use the open realm ...

Customize a Realm Configuration

You can add optional arguments to the RealmConfiguration to control the specifics of the realm that you would like to open, including:

• Defining a custom file name and file path

• Passing an encryption key to encrypt a realm

• Compacting a realm to reduce its file size

• Specifying a schema version or migration block when making schema changes

• Flagging whether Realm should delete the realm file if a migration is required

For more information on specific configuration implementations, refer to Manage Realm Files - Kotlin SDK.

To configure a realm with non-default values, create the RealmConfiguration through RealmConfiguration.Builder.build() and pass any properties you want to set. Then, pass the resulting RealmConfiguration to Realm.open().

In the following example, the RealmConfiguration specifies a custom name and directory ("my-directory-path/myRealmName.realm") and encryption key:

// Create a realm configuration with configuration builder
// and pass all optional arguments
val config = RealmConfiguration.Builder(
    schema = setOf(Frog::class, Person::class)
)
    .name("myRealmName.realm")
    .directory("my-directory-path")
    .encryptionKey(myEncryptionKey)
    .build()
// Open the realm with the configuration object
val realm = Realm.open(config)
Log.v("Successfully opened realm: ${realm.configuration.name}")
// ... use the open realm ...

val config = RealmConfiguration.Builder(
    schema = setOf(Frog::class, Person::class)
)
    .initialData {
        copyToRealm(Frog().apply { name = "Kermit" })
        copyToRealm(Person().apply { name = "Jim Henson" })
    }
    .build()
val realm = Realm.open(config)
Log.v("Successfully opened realm: ${realm.configuration.name}")
// Opened realm includes the initial data
val initialFrog = realm.query<Frog>().find().first()
val initialPerson = realm.query<Person>().find().first()
Log.v("Realm initialized with: ${initialFrog.name} and ${initialPerson.name}")

Find a Realm File Path

To find the file path for a .realm file, use the realm.configuration.path property:

val realmPath = realm.configuration.path
Log.v("Realm path: $realmPath")

Close a Realm

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

realm.close()

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

• Synced realm to a synced realm for a different user

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.

// Instantiate the synced realm with your App ID
val app = App.create(YOUR_APP_ID)
runBlocking {
    val user = app.login(credentials)
    // Create the synced realm configuration
    val syncConfig = SyncConfiguration.Builder(user, setOf(Frog::class))
        .initialSubscriptions { realm ->
            add(realm.query<Frog>(),"all-frogs")
        }
        .build()
    // Open the synced realm and add data to it
    val syncRealm = Realm.open(syncConfig)
    Log.v("Successfully opened realm: ${syncRealm.configuration.name}")
    syncRealm.write {
        this.copyToRealm(Frog().apply {
            name = "Kermit"
        })
    }
    // Wait for write to sync
    syncRealm.syncSession.uploadAllLocalChanges(30.seconds)
    // Create the local realm
    val localConfig = RealmConfiguration.Builder(setOf(Frog::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 Frog object is available in the new realm
    val frog = localRealm.query<Frog>().find().first()
    Log.v("Copied Frog: ${frog.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.

runBlocking {
    // Create the unencrypted realm
    val unencryptedConfig = RealmConfiguration.Builder(setOf(Frog::class))
        .name("unencrypted.realm")
        .build()
    // Open the realm and add data to it
    val unencryptedRealm = Realm.open(unencryptedConfig)
    unencryptedRealm.write {
        this.copyToRealm(Frog().apply {
            name = "Kermit"
        })
    }
    // ... Generate encryption key ...
    // Create the encrypted realm
    val encryptedConfig = RealmConfiguration.Builder(setOf(Frog::class))
        .name("encrypted.realm")
        .encryptionKey(encryptionKey)
        .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 Frog object is available in the new realm
    val frog = encryptedRealm.query<Frog>().find().first()
    Log.v("Copied Frog: ${frog.name}")
    encryptedRealm.close()
}

runBlocking {
    // Create the in-memory realm
    val inMemoryConfig = RealmConfiguration.Builder(setOf(Frog::class))
        .name("inMemory.realm")
        .inMemory()
        .build()
    // Open the realm and add data to it
    val inMemoryRealm = Realm.open(inMemoryConfig)
    inMemoryRealm.write {
        this.copyToRealm(Frog().apply {
            name = "Kermit"
        })
    }
    // Create the local realm
    val localConfig = RealmConfiguration.Builder(setOf(Frog::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 Frog object is available in the new realm
    val frog = localRealm.query<Frog>().find().first()
    Log.v("Copied Frog: ${frog.name}")
    localRealm.close()
}