Realm Kotlin SDK

Android benchmarks utilize Jetpack Microbenchmarks. You can run them via Gradle or directly from your IDE as a normal Android Integration Test.

Important Note on Emulators: While benchmarks can run on emulators, results are often unreliable due to high variance. For accurate results, use real devices. If you must use an emulator, use API level 29 or below to avoid scoped storage restrictions.

To run via Gradle:

./gradlew androidApp:connectedCheck -e no-isolated-storage true

You can use the Realm Kotlin SDK within the commonMain source set of a Kotlin Multiplatform project to provide a single, shared implementation of data persistence logic for both Android and iOS.

In a typical KMM architecture, you implement your repositories (e.g., an ExpressionRepository) once in the shared module. This allows the shared business logic (e.g., a Calculator class) to trigger database operations that are then automatically available to all platform-specific targets.

// Example conceptual structure in commonMain
class ExpressionRepository(private val realm: Realm) {
    // Shared implementation for Android and iOS
    fun saveCalculation(expression: String) {
        realm.write { 
            // ... logic to persist data
        }
    }
}

Benchmark data for Android is typically stored on the device. You can pull the data to your local machine using adb pull to a specific directory:

adb pull /sdcard/Android/media/io.realm.kotlin.benchmarks.android.test ./benchmark-data/android/

To use Realm, define your data models as classes that implement the RealmObject interface. These classes represent the schema of your database. You can define relationships between objects (e.g., a Person having a Dog).

class Person : RealmObject {
    var name: String = "Foo"
    var dog: Dog? = null
}

class Dog : RealmObject {
    var name: String = ""
    var age: Int = 0
}

To access the database, you must first define a RealmConfiguration specifying the schema (the set of RealmObject classes used) and then call Realm.open(configuration).

// use the RealmConfiguration.Builder() for more options
val configuration = RealmConfiguration.create(schema = setOf(Person::class, Dog::class)) 
val realm = Realm.open(configuration)

JVM benchmarks use the Java Microbenchmarking Harness (JMH). These must be run from the command line.

Note on caching: If a benchmark file already exists, JMH will exit without re-running. To ensure a fresh run, execute ./gradlew clean before running the benchmark.

To run all JVM benchmarks:

./gradlew jvmApp:clean jvmApp:jmh

To run a specific subset of benchmarks using a regex pattern:

./gradlew jvmApp:clean jvmApp:jmh -Pjmh.include="BulkWrite*"

Benchmark results are saved to: /jvmApp/build/reports/benchmarks.json

All changes to the database must occur within a write transaction. You can use writeBlocking for synchronous writes or write for asynchronous writes using Kotlin coroutines. Inside the transaction block, use copyToRealm(object) to persist a plain Kotlin object into the Realm.

// plain old kotlin object
val person = Person().apply {
    name = "Carlo"
    dog = Dog().apply { name = "Fido"; age = 16 }
}

// Persist it in a transaction
realm.writeBlocking { // this : MutableRealm
    val managedPerson = copyToRealm(person)
}

// Asynchronous updates with Kotlin coroutines
CoroutineScope(context).async {
    realm.write { // this : MutableRealm
        val managedPerson = copyToRealm(person)
    }
}

Deletions must be performed within a write transaction. You can delete objects based on a query, from a query result, or by passing individual managed objects to the delete() method.

// delete all Dogs
realm.writeBlocking {
    // Selected by a query
    val query = this.query<Dog>()
    delete(query)

    // From a query result
    val results = query.find()
    delete(results)

    // From individual objects
    results.forEach { delete(it) }
}

To update an object, first find it using a query. Within a write transaction, use findLatest(object) to get the live, managed version of the object before applying changes.

// Find the first Person without a dog
realm.query<Person>("dog == NULL LIMIT(1)")
    .first()
    .find()
    ?.also { personWithoutDog ->
        // Add a dog in a transaction
        realm.writeBlocking {
            findLatest(personWithoutDog)?.dog = Dog().apply { name = "Laika"; age = 3 }
        }
    }