Local data with Room

The three parts

1@Entity(tableName = "note")2data class Note(3    @PrimaryKey val id: String,4    val title: String,5    val body: String,6    val updatedAt: Long,7)8 9@Dao10interface NoteDao {11    @Query("SELECT * FROM note ORDER BY updatedAt DESC")12    fun observeAll(): Flow<List<Note>>13 14    @Query("SELECT * FROM note WHERE id = :id")15    suspend fun get(id: String): Note?16 17    @Upsert18    suspend fun save(note: Note)19}20 21@Database(entities = [Note::class], version = 1, exportSchema = true)22abstract class AppDatabase : RoomDatabase() {23    abstract fun notes(): NoteDao24}

Build the database once and share it (a DI singleton):

1val db = Room.databaseBuilder<AppDatabase>(context, "app.db").build()

Threads and observation

Room's suspend DAO functions are main-safe: they run on Room's own executor and resume you where you were. In Room 2.x, a blocking (non-suspend) query called on the main thread throws unless you explicitly allow it, which you shouldn't. A Flow return type turns a query into a live view: Room re-runs it whenever a write to a table it reads commits, so the screen updates itself after a save anywhere in the app.

Group writes that belong together in a transaction (@Transaction on a DAO method, or db.withTransaction { ... } in 2.x) so observers see all of them or none.

Migrations

The schema version is part of your app's contract with every installed copy. When you change an entity, bump version and tell Room how to get there:

1@Database(2    entities = [Note::class],3    version = 2,4    autoMigrations = [AutoMigration(from = 1, to = 2)],   // needs exported schema JSON for both versions5)6abstract class AppDatabase : RoomDatabase() { /* ... */ }7 8// For changes Room can't infer (renames, splitting tables), write it:9val MIGRATION_2_3 = object : Migration(2, 3) {10    override fun migrate(db: SupportSQLiteDatabase) {11        db.execSQL("ALTER TABLE note ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0")12    }13}

Keep the exported schema files in version control and test migrations with MigrationTestHelper. Without a migration path, opening the database fails; fallbackToDestructiveMigration() makes it wipe the data instead, which is only acceptable for pure caches.

Room 2.x and Room 3.0

Version note: most apps today use Room 2.x (package androidx.room). Room 3.0, released in July 2026, moves to a new package (androidx.room3), is built around Kotlin Multiplatform, generates Kotlin only, requires KSP (no KAPT), and makes database operations coroutine-based: DAO functions must be suspend unless they return a reactive type like Flow. The SupportSQLite APIs (used in the migration above) are replaced by SQLite driver APIs unless you add the compatibility wrapper. The entity, DAO and database annotations stay the same, so the model on this page carries over.

Room as the source of truth

A common offline-first shape: the UI observes Room; a repository fetches from the network and writes into Room; the Flow delivers the update. The screen works offline, survives process death, and has one place where data comes from.