Room — a real database

Where has everything gone?

Every piece of state you have written so far lives in memory. Memory is emptied when the app closes. A notes app that forgets your notes when you swipe it away is not a notes app.

You need persistence: data written to the phone's storage, where it survives the app closing, the phone restarting, and three weeks of not being opened.

Android's answer is Room, and it sits on top of a database that is already on every phone in the world.

Three pieces and nothing else

Room needs three things from you.

You write the what. Room's code generator writes the how at build time.

1. The entity: a table, written as a class

1@Entity(tableName = "notes")
2data class Note(
3  @PrimaryKey(autoGenerate = true)
4  val id: Long = 0L,
5  val title: String = "",
6  val body: String = "",
7  val updatedAt: Long = 0L
8)

That is the real Note from Pocket Notes, and it produces this table:

One class, one table. One property, one column.

@PrimaryKey(autoGenerate = true) marks the column that must be unique. With autoGenerate, saving a Note whose id is 0 means "you pick one" — so id = 0 becomes the app's word for brand new, which is why the editor route in Lesson 4.4 was "editor/0".

updatedAt is a Long rather than a date, because SQLite stores numbers, text and blobs — nothing else. Milliseconds since 1970 is a number, so it needs no translation. Anything SQLite does not recognise needs a type converter, and the error you get without one is in the Error Doctor below.

2. The DAO: what you want done

3. The database

1@Database(
2  entities = [Note::class],
3  version = 1,
4  exportSchema = false
5)
6abstract class NotesDatabase : RoomDatabase() {
7  abstract fun noteDao(): NoteDao
8}

Abstract, because Room generates the real subclass. version matters enormously and is covered below.

Opening a database is expensive, and opening the same file twice can corrupt it, so an app opens it once and shares it — a singleton:

1companion object {
2
3  @Volatile
4  private var instance: NotesDatabase? = null
5
6  fun get(context: Context): NotesDatabase {
7    return instance ?: synchronized(this) {
8      val created = Room.databaseBuilder(
9        context.applicationContext,
10        NotesDatabase::class.java,
11        "pocket-notes.db"
12      ).build()
13      instance = created
14      created
15    }
16  }
17}

applicationContext is deliberate: holding an Activity here would leak a screen for the lifetime of the app. synchronized means two coroutines arriving at the same instant still produce one database.

Wiring up KSP

Room's generator runs through KSP, declared as a Gradle plugin:

1plugins {
2  alias(libs.plugins.android.application)
3  alias(libs.plugins.kotlin.android)
4  alias(libs.plugins.kotlin.compose)
5  alias(libs.plugins.ksp)
6}
7
8dependencies {
9  implementation(libs.androidx.room.runtime)
10  implementation(libs.androidx.room.ktx)
11  ksp(libs.androidx.room.compiler)
12}

Note the third line in dependencies: ksp(...), not implementation(...). The compiler is a build-time tool. Adding it as an implementation dependency would ship the entire code generator inside your APK and generate nothing.

1[versions]
2room = "2.6.1"
3ksp = "2.1.0-1.0.29"

The KSP version has two halves: the Kotlin version it matches (2.1.0) and its own release number. They must line up with your Kotlin version exactly — a mismatch is one of the errors below.

The main thread rule

The main thread draws every frame and handles every tap. Block it for 16 milliseconds and you drop a frame. Block it for five seconds and Android shows the "app isn't responding" dialog.

Disk reads take an unpredictable amount of time. So Room refuses:

java.lang.IllegalStateException: Cannot access database on the main thread since it may potentially lock the UI for a long period of time.

This is a guard rail, not an insult. Mark DAO functions suspend, or return a Flow, and Room handles the threading for you — you will never see this error.

Changing the shape later

Add a field to Note and you have changed the schema. The database on the user's phone still has the old columns. Room notices and refuses to open:

Room cannot verify the data integrity. Looks like you've changed schema but forgot to update the version number.

Bump version = 1 to version = 2 and you get the next refusal:

A migration from 1 to 2 was required but not found.

That is Room asking the only question that matters: what should happen to data that already exists? You answer with a migration:

1val MIGRATION_1_2 = object : Migration(1, 2) {
2  override fun migrate(db: SupportSQLiteDatabase) {
3    db.execSQL(
4      "ALTER TABLE notes ADD COLUMN pinned " +
5        "INTEGER NOT NULL DEFAULT 0"
6    )
7  }
8}

Then .addMigrations(MIGRATION_1_2) on the builder.