realm-kotlin

3.0.0indexed

Mobile database runs directly on phones, tablets, or wearables, offering object-oriented data models, efficient resource usage, and offline capabilities. Includes real-time data sync across users and devices.

AndroidJVMNative·realm/realm-kotlin

1.1k

Stars

Used by

dependents

—

Health

/ 100

[!WARNING] We announced the deprecation of Atlas Device Sync + Realm SDKs in September 2024. For more information please see:

SDK Deprecation

Device Sync Deprecation

For a version of Realm Kotlin without sync features, install version 3.0.0+ or see the community git branch.

Realm is a mobile database that runs directly inside phones, tablets or wearables.

This repository holds the source code for the Kotlin SDK for Realm, which runs on Kotlin Multiplatform and Android.

Why Use Realm

Intuitive to Developers: Realm’s object-oriented data model is simple to learn, doesn’t need an ORM, and lets you write less code.
Built for Mobile: Realm is fully-featured, lightweight, and efficiently uses memory, disk space, and battery life.
Designed for Offline Use: Realm’s local database persists data on-disk, so apps work as well offline as they do online.

General Availability

The Realm Kotlin SDK is GA.

Documentation can be found here.

Sample projects can be found here.

If you are upgrading from a previous beta release of Realm Kotlin, please see the CHANGELOG for the full list of changes.

If you are migrating from Realm Java, please see the Migration Guide.

Usage

Installation

Installation differs slightly depending on the type of project and whether or not you are using Device Sync. See the details in the documentation:

Also pay attention to restrictions on which versions of Kotlin and other dependencies that are supported. You can read more in the version compatibility matrix.

Define model

Start writing your database logic by first defining your model.

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

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

Open Database

Define a RealmConfiguration with the database schema, then open the Realm using it.

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

Write

Persist some data by instantiating the model object and copying it into the open Realm instance.

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

Query

The query language supported by Realm is inspired by Apple’s NSPredicate, see more examples here

// All persons
import io.realm.kotlin.ext.query

val all = realm.query<Person>().find()

// Persons named 'Carlo'
val personsByNameQuery: RealmQuery<Person> = realm.query<Person>("name = $0", "Carlo")
val filteredByName: RealmResults<Person> = personsByNameQuery.find()

// Person having a dog aged more than 7 with a name starting with 'Fi'
 filteredByDog = realm.query<Person>(, , ).find()


CoroutineScope(context).async {
    personsByNameQuery.asFlow().collect { result: ResultsChange<Person> ->
        println()
    }
}

Update

// 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 }
        }
    }

Delete

Use the result of a query to delete from the database.

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

Observing data changes

Realm support asynchronous observers on all its data structures.

Realm

A Realm can be observed globally for changes on its data.

realm.asFlow()
    .collect { realmChange: RealmChange<Realm> ->
        when (realmChange) {
            is InitialRealm<*> -> println("Initial Realm")
            is UpdatedRealm<*> -> println("Realm updated")
        }
    }

RealmObject

Realm objects can be observed individually. A list of the changed field names is provided on each update.

person.asFlow().collect { objectChange: ObjectChange<Person> ->
        when (objectChange) {
            is InitialObject -> println("Initial object: ${objectChange.obj.name}")
            is UpdatedObject -> 
                println("Updated object: ${objectChange.obj.name}, changed fields: ${objectChange.changedFields.size}")
            is DeletedObject -> println("Deleted object")
        }
    }

RealmLists

Realm data structures can be observed too. On RealmList on each update you receive what positions were inserted, changed or deleted.

person.addresses.asFlow()
        .collect { listChange: ListChange<String> ->
            when (listChange) {
                is InitialList -> println("Initial list size: ${listChange.list.size}")
                is UpdatedList -> 
                    println("Updated list size: ${listChange.list.size} insertions ${listChange.insertions.size}")
                is DeletedList -> println("Deleted list")
            }
        }

RealmQuery

Query results are also observable, and like RealmList on each update, the inserted, changed and deleted indices are also provided.

realm.query<Person>().asFlow()
    .collect { resultsChange: ResultsChange<Person> ->
        when (resultsChange) {
            is InitialResults -> println("Initial results size: ${resultsChange.list.size}")
            is UpdatedResults -> 
                println("Updated results size: ${resultsChange.list.size} insertions ${resultsChange.insertions.size}")
        }
    }

RealmSingleQuery

Single element queries allow observing a RealmObject that might not be in the realm.

realm.query<Person>("name = $0", "Carlo").first().asFlow()
    .collect { objectChange: SingleQueryChange<Person> ->
        when (objectChange) {
            is PendingObject -> println("Pending object")
            is InitialObject -> println("Initial object: ${objectChange.obj.name}")
            is UpdatedObject -> 
                println("Updated object: ${objectChange.obj.name}, changed fields: ${objectChange.changedFields.size}")
             DeletedObject -> println()
        }
    }

Next: head to the full KMM example.

Using Snapshots

If you want to test recent bugfixes or features that have not been packaged in an official release yet, you can use a -SNAPSHOT release of the current development version of Realm via Gradle, available on Maven Central

Groovy

// Global build.gradle
buildscript {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://oss.sonatype.org/content/repositories/snapshots'
        }
    }
    dependencies {
        classpath 'io.realm.kotlin:gradle-plugin:<VERSION>'
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://oss.sonatype.org/content/repositories/snapshots'
        }
    }
}

// Module build.gradle

// Don't cache SNAPSHOT (changing) dependencies.
configurations.all {
    resolutionStrategy.cacheChangingModulesFor 0, 'seconds'
}

apply plugin: "io.realm.kotlin"

Kotlin

// Global build.gradle

buildscript {
    dependencies {
        classpath("io.realm.kotlin:gradle-plugin:<VERSION>-SNAPSHOT")
    }
}

repositories {
    google()
    mavenCentral()
    maven {
        url = uri("https://oss.sonatype.org/content/repositories/snapshots")
    }
}

// Module build.gradle

plugins {
    id("io.realm.kotlin")
}
kotlin {
    sourceSets {
        val commonMain  by getting {
            dependencies {
                implementation("io.realm.kotlin:library-base:<VERSION>-SNAPSHOT")
            }
        }
    }
}     

// Don't cache SNAPSHOT (changing) dependencies.
configurations.all {
    resolutionStrategy.cacheChangingModulesFor(0,TimeUnit.SECONDS)
}

See Config.kt for the latest version number.

Version Compatibility Matrix

With Kotlin Multiplatform still in Beta and the Compiler Plugin APIs being experimental, there might be restrictions on what versions of Kotlin the Realm Kotlin SDK supports. In the matrix below, you will find the minimum supported version for the dependencies of each Realm release.

While we strive to be compatible with other plugins and libraries like Android Gradle Plugin, Jetpack Compose and Compose Multiplatform, these plugins (and others) have their own version restrictions, so if you are running into build errors this would be the first thing to check:

You can find Kotlin version requirements for these libraries and plugins here:

Kotlin Memory Model and Coroutine compatibility

Realm Kotlin 1.3.0 and above only works with the new Kotlin Native memory model. This is also the default memory model from Kotlin 1.7.20 and onwards. This mean that you need the default Kotlin Coroutine library 1.6.0 and above and not the -mt variant, which have also been deprecated.

See the ## Compatibility section of the CHANGELOG for information about exactly which versions are compatible with a given version of Realm Kotlin.

When upgrading older projects, it is important to be aware that certain Gradle properties will control the memory model being used. So, if you have the Gradle properties below defined in your project. Make sure they are set to the values shown:

kotlin.native.binary.memoryModel=experimental
kotlin.native.binary.freezing=disabled

See https://kotlinlang.org/docs/native-memory-manager.html for more details about the new memory model.

Contributing

See CONTRIBUTING.md for more details!

Code of Conduct

This project adheres to the MongoDB Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to community-conduct@mongodb.com.

License

Realm Kotlin is published under the Apache 2.0 license.

This product is not being made available to any person located in Cuba, Iran, North Korea, Sudan, Syria or the Crimea region, or to any other person that is not eligible to receive the product under U.S. law.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

datastore★ 6.0k

androidxAsynchronous, consistent, transactional storage replacing SharedPreferences; supports preferences and typed objects with Proto/JSON serialization, optional Rx adapters, and atomic updates.Shared: storage

sqlite★ 6.0k

androidxAbstract SQLite interfaces with basic implementations, plus framework bindings and language-friendly extensions to build customized database access layers; intended as a lightweight alternative to higher-level ORMs.Shared: storage

Store★ 3.4k

MobileNativeFoundationTyped repository for managing data flow from local and network sources, supporting CRUD operations, data validation, conversion, synchronization, and error tracking.Shared: storage

multiplatform-settings★ 2.2k

russhwolfLibrary for persisting key-value data in common code across multiple platforms. Features include platform-specific settings implementations, factory classes, property delegates, listeners, and experimental support for serialization and coroutines.Shared: storage

KStore★ 664

xxfastAssists in saving and restoring objects to and from disk using coroutines, serialization, and Okio. Features include read-write locks, in-memory caching, default values, and migration support.Shared: storage

flower★ 310

hadiyarajeshSimplifies networking and database caching, handling resource states efficiently and ensuring a fluid app experience. Integrates with Ktorfit, Retrofit, or core networking modules for flexible implementation.Shared: storage

2.3.0	Kotlin 2.0.20+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 7.2 - 8.5 The new memory model only.
2.0.0	Kotlin 2.0.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 7.2 - 8.5 The new memory model only.
1.16.0	Kotlin 1.9.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 6.8.3 - 8.5 The new memory model only.
1.15.0	Kotlin 1.9.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 6.8.3 - 8.5 The new memory model only.
1.14.0	Kotlin 1.9.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 6.8.3 - 8.5 The new memory model only.
1.13.0	Kotlin 1.9.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 6.8.3 - 8.5 The new memory model only.
1.12.0	Kotlin 1.8.20+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 6.8.3 - 7.6.1. The new memory model only.
1.11.0	Kotlin 1.8.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 6.8.3 - 7.6.1. The new memory model only.
1.10.0	Kotlin 1.8.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.7.0+. Gradle 6.8.3 - 7.6.1. The new memory model only.
1.9.0	Kotlin 1.8.0+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.8.3 - 7.6.1. The new memory model only.
1.8.0	Kotlin 1.7.20+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.7.1	Kotlin 1.7.20+ AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.7.0	Kotlin 1.7.20 - 1.8.10 AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.6.1	Kotlin 1.7.20+. AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.6.0	Kotlin 1.7.20 - 1.7.21. AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.5.2	Kotlin 1.7.20 - 1.7.21. AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.5.1	Kotlin 1.7.20 - 1.7.21. AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.5.0	Kotlin 1.7.20 - 1.7.21. AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.4.0	Kotlin 1.7.20 - 1.7.21. AtomicFu 0.18.3+. Ktor 2.1.2+. Coroutines 1.6.4+. Gradle 6.7.1 - 7.6.1. The new memory model only.
1.3.0	Kotlin 1.6.10 - 1.7.10. AtomicFu 0.17.0+. Ktor 1.6.8. Coroutines 1.6.0-native-mt. Gradle 6.1.1 - 7.6.1.
1.2.0	Kotlin 1.6.10 - 1.7.10. AtomicFu 0.17.0+. Ktor 1.6.8. Coroutines 1.6.0-native-mt. Gradle 6.1.1 - 7.6.1.
1.1.0	Kotlin 1.6.10 - 1.7.10. AtomicFu 0.17.0+. Ktor 1.6.8. Coroutines 1.6.0-native-mt. Gradle 6.1.1 - 7.6.1.
1.0.2	Kotlin 1.6.10 - 1.7.10. AtomicFu 0.17.0+. Ktor 1.6.8. Coroutines 1.6.0-native-mt. Gradle 6.1.1 - 7.6.1.
1.0.1	Kotlin 1.6.10 - 1.7.10. AtomicFu 0.17.0+. Ktor 1.6.8. Coroutines 1.6.0-native-mt. Gradle 6.1.1 - 7.6.1.
1.0.0	Kotlin 1.6.10 - 1.7.10. AtomicFu 0.17.0+. Ktor 1.6.8. Coroutines 1.6.0-native-mt. Gradle 6.1.1 - 7.6.1.