Persist Data with Room

In lesson 32 you learned SQL. Now you will use it from Kotlin. Room is the Jetpack library that gives your app a SQLite database without you writing cursor loops or SQL boilerplate. You describe your tables as Kotlin classes, your queries as annotated functions, and Room generates the code at build time and checks your SQL while you compile.

You will build Inventory, a stock-keeping app for a small shop (think of a provision store in Bodija market): a list of items with name, price and quantity, a screen to add an item, and a screen to view, sell, edit and delete one. All data stays on the phone and survives closing the app, rebooting the phone and process death. Then you will plan the Bus Schedule practice app.

This lesson covers the four items of Pathway 2, Unit 6 of the official Android Basics with Compose course that deal with Room: Using Room Kotlin APIs, Persist data with Room, Read and update data with Room and Practice: Build Bus Schedule app.

A note on versions. Room has a new major version, Room 3.0, published under new names (androidx.room3). Room 2.x (androidx.room) is in maintenance mode. Older tutorials, including some Google codelabs, still show Room 2.x. This lesson teaches the current Room 3 API, shows the Room 2.x equivalent wherever it differs, and tells you which to check. Always read the official setup page for the exact current versions and imports (https://developer.android.com/training/data-storage/room), because this is a fast-moving library.

By the end you will be able to:

• Define an entity, a DAO and a database class.
• Add Room with KSP using the version catalog.
• Write @Insert, @Update, @Delete and @Query functions, using suspend and Flow.
• Create one database instance and expose it through a repository and the app container (lesson 30).
• Build ViewModels that expose database data as StateFlow with stateIn(WhileSubscribed(5000)).
• Validate input before saving, and format money safely.
• Inspect the live database with Android Studio's Database Inspector.
• Test a DAO with an in-memory database.
• Explain schema migrations.

Big idea: Room turns "rows in a table" into "objects in a list", and turns "the table changed" into "the Flow emitted again". Your UI never asks "did anything change?". It just collects.

• SQL (lesson 32). You will write SELECT, WHERE, ORDER BY inside annotations.
• Flow and stateIn (lesson 33).
• Repositories and the app container (lesson 30).
• Coroutines and suspend (lesson 28).
• ViewModel, UI state, and navigation (lessons 24 to 26).

  Kotlin data class          interface of functions        abstract class
 +------------------+       +------------------------+    +--------------------+
 |  @Entity  Item   | <---- |  @Dao  ItemDao         | <--|  @Database         |
 |  one TABLE       |       |  @Insert @Query ...    |    |  InventoryDatabase |
 +------------------+       +------------------------+    +--------------------+
   describes a row           describes operations           ties it together;
                                                            gives you the DAO

Room generates the implementation of the DAO and the database for you at build time. Because it reads your annotations and SQL during compilation, mistakes become build errors.

Why suspend and Flow?

A database is slow compared with memory (it reads a file), so Room refuses to run queries on the main thread. Two ways to follow that rule:

A Flow-returning function is not suspend (the flow itself is cold, lesson 33). Room runs the query on a background thread and re-runs it automatically when the underlying table is modified. That is why a list on screen updates the instant you insert a row, with no refresh code.

Create a new Empty Activity project called Inventory (package com.example.inventory). Room needs KSP (Kotlin Symbol Processing) to generate code, and Room 3 supports no other processor (no KAPT).

Look up the current versions of Room (https://developer.android.com/jetpack/androidx/releases/room3) and the KSP plugin matching your Kotlin version (https://github.com/google/ksp/releases) and fill in:

[versions]
room = "<latest stable Room 3>"
ksp = "<KSP version that matches your Kotlin version>"
[libraries]
androidx-room-runtime = { group = "androidx.room3", name = "room3-runtime", version.ref = "room" }
androidx-room-compiler = { group = "androidx.room3", name = "room3-compiler", version.ref = "room" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

plugins {
 alias(libs.plugins.ksp)
}
dependencies {
 implementation(libs.androidx.room.runtime)
 ksp(libs.androidx.room.compiler)
}

Also add alias(libs.plugins.ksp) apply false to the root build.gradle.kts plugin block, then Sync Now. The KSP version string starts with your Kotlin version (for example a 2.x.y-1.0.z pattern), so choose the one for the Kotlin version in your catalog.

You also need a SQLite driver. Room 3 is built on the androidx.sqlite driver APIs. For Android the simplest option is the framework driver that wraps the SQLite already on the phone; if your setup page shows AndroidSQLiteDriver, use that (artifact androidx.sqlite:sqlite-framework; check the current page for the exact coordinate). A bundled driver (androidx.sqlite:sqlite-bundled) ships its own SQLite so behaviour is identical on every phone, at the price of a larger app.

Room 2.x equivalents. If your project (or a tutorial) uses Room 2.x: artifacts are androidx.room:room-runtime and androidx.room:room-compiler, plus androidx.room:room-ktx for coroutine and Flow support in older versions; imports start androidx.room. (not androidx.room3.); @TypeConverter stays @TypeConverter (it is @ColumnTypeConverter in Room 3); you do not have to set a driver; and blocking DAO functions are allowed (but should never be called on the main thread). The concepts in this lesson are identical.

package com.example.inventory.data
import androidx.room3.Entity
import androidx.room3.PrimaryKey
@Entity(tableName = "items")
data class Item(
 @PrimaryKey(autoGenerate = true) val id: Int = 0,
 val name: String,
 val priceKobo: Long,
 val quantity: Int
)

• @Entity(tableName = "items") makes the class a table named items (otherwise the table takes the class name).
• @PrimaryKey(autoGenerate = true) lets SQLite choose the id. The = 0 default means "not saved yet": when you insert an Item(name = ..., ...) with id = 0, Room asks the database to generate one.
• Each property becomes a column of the matching type (Int and Long become INTEGER, String becomes TEXT).
• Money is stored as a whole number of kobo (100 kobo = 1 naira), the integer approach from lesson 32. ₦1,250.50 is 125050.

Other annotations you will meet: @ColumnInfo(name = "item_name") to rename a column, @Ignore to skip a property, and indices for indexes.

package com.example.inventory.data
import androidx.room3.Dao
import androidx.room3.Delete
import androidx.room3.Insert
import androidx.room3.OnConflictStrategy
import androidx.room3.Query
import androidx.room3.Update
import kotlinx.coroutines.flow.Flow
@Dao
interface ItemDao {
 @Insert(onConflict = OnConflictStrategy.IGNORE)
 suspend fun insert(item: Item)
 @Update
 suspend fun update(item: Item)
 @Delete
 suspend fun delete(item: Item)
 @Query("SELECT * FROM items WHERE id = :id")
 fun getItem(id: Int): Flow<Item?>
 @Query("SELECT * FROM items ORDER BY name ASC")
 fun getAllItems(): Flow<List<Item>>
}

Read each one:

A few helpful details:

• The SQL in @Query is validated at compile time against your entities. Misspell itemz and the build fails with a clear message.
• In Room 3, non-observable DAO functions must be suspend. The insert, update and delete functions return Unit here, but they can also return the new row id (Long) or a count of affected rows (Int).
• Flow<Item?> is nullable because getItem may match nothing.

package com.example.inventory.data
import android.content.Context
import androidx.room3.Database
import androidx.room3.Room
import androidx.room3.RoomDatabase
import androidx.sqlite.driver.AndroidSQLiteDriver
@Database(entities = [Item::class], version = 1, exportSchema = true)
abstract class InventoryDatabase : RoomDatabase() {
 abstract fun itemDao(): ItemDao
 companion object {
 fun build(context: Context): InventoryDatabase =
 Room.databaseBuilder<InventoryDatabase>(
 context = context.applicationContext,
 name = "inventory_database"
 )
 .setDriver(AndroidSQLiteDriver())
 .build()
 }
}

• @Database(entities = [...], version = 1) lists every table. Increase version whenever you change the schema (lesson section on migrations).
• exportSchema = true writes a JSON copy of each version of your schema into a folder you commit; Room uses it for tests and automatic migrations. Configure the output folder as the official migration guide shows (a room { schemaDirectory(...) } block or a KSP argument, depending on the Room version).
• abstract fun itemDao() is how you get the DAO. Room generates the body.
• context.applicationContext avoids leaking an Activity (lesson 24).
• Create one Database instance for the whole app. Building one is expensive. In lesson 30 you learned the right home for a long-lived object: the app container.

Check your imports against the official setup page: package and driver names changed between Room 2 and 3, and are the most likely thing to differ in your project.

Wire it into the container

// AppContainer.kt
interface AppContainer {
 val itemsRepository: ItemsRepository
}
class DefaultAppContainer(private val context: Context) : AppContainer {
 override val itemsRepository: ItemsRepository by lazy {
 OfflineItemsRepository(InventoryDatabase.build(context).itemDao())
 }
}

// InventoryApplication.kt (register with android:name in the manifest)
class InventoryApplication : Application() {
 lateinit var container: AppContainer
 override fun onCreate() {
 super.onCreate()
 container = DefaultAppContainer(this)
 }
}

The repository

// ItemsRepository.kt
interface ItemsRepository {
 fun getAllItemsStream(): Flow<List<Item>>
 fun getItemStream(id: Int): Flow<Item?>
 suspend fun insertItem(item: Item)
 suspend fun deleteItem(item: Item)
 suspend fun updateItem(item: Item)
}
class OfflineItemsRepository(private val itemDao: ItemDao) : ItemsRepository {
 override fun getAllItemsStream(): Flow<List<Item>> = itemDao.getAllItems()
 override fun getItemStream(id: Int): Flow<Item?> = itemDao.getItem(id)
 override suspend fun insertItem(item: Item) = itemDao.insert(item)
 override suspend fun deleteItem(item: Item) = itemDao.delete(item)
 override suspend fun updateItem(item: Item) = itemDao.update(item)
}

The name OfflineItemsRepository hints at the offline-first design in lesson 62: the database is the source of truth. Later, a NetworkItemsRepository could sync with a server without changing any ViewModel.

The home list

// HomeViewModel.kt
data class HomeUiState(val itemList: List<Item> = emptyList())
class HomeViewModel(itemsRepository: ItemsRepository) : ViewModel() {
 val homeUiState: StateFlow<HomeUiState> =
 itemsRepository.getAllItemsStream()
 .map { HomeUiState(it) }
 .stateIn(
 scope = viewModelScope,
 started = SharingStarted.WhileSubscribed(5_000),
 initialValue = HomeUiState()
 )
}

This is lesson 33's stateIn recipe. Insert a row anywhere in the app and this StateFlow emits, and the list redraws. Imports needed: androidx.lifecycle.ViewModel, androidx.lifecycle.viewModelScope, kotlinx.coroutines.flow.* (StateFlow, SharingStarted, map, stateIn).

Entry with validation and a money helper

// ItemEntryViewModel.kt
data class ItemDetails(
 val id: Int = 0,
 val name: String = "",
 val price: String = "", // typed by the user, in naira, e.g. "1250.50"
 val quantity: String = ""
)
data class ItemUiState(
 val itemDetails: ItemDetails = ItemDetails(),
 val isEntryValid: Boolean = false
)
fun ItemDetails.toItem(): Item = Item(
 id = id,
 name = name.trim(),
 priceKobo = nairaTextToKobo(price) ?: 0L,
 quantity = quantity.toIntOrNull() ?: 0
)
fun Item.toItemDetails(): ItemDetails = ItemDetails(
 id = id,
 name = name,
 price = "%d.%02d".format(priceKobo / 100, priceKobo % 100),
 quantity = quantity.toString()
)
fun nairaTextToKobo(text: String): Long? {
 val clean = text.trim()
 if (!Regex("""\d+(\.\d{1,2})?""").matches(clean)) return null
 val parts = clean.split(".")
 val naira = parts[0].toLongOrNull() ?: return null
 val kobo = parts.getOrNull(1)?.padEnd(2, '0')?.toLongOrNull() ?: 0L
 return naira * 100 + kobo
}

nairaTextToKobo("1250.5") gives 125050 (the .5 is padded to 50), "300" gives 30000, and "abc" or "1.234" give null. Working with text and then converting once at the boundary keeps floating-point numbers out of your money entirely. ("%d.%02d".format(...) uses the device locale for digits; in locales that use different numerals you would format differently, a trap lesson 20 explained. For a shop-owner app, test it in your target locale.)

class ItemEntryViewModel(private val itemsRepository: ItemsRepository) : ViewModel() {
 var itemUiState by mutableStateOf(ItemUiState())
 private set
 fun updateUiState(details: ItemDetails) {
 itemUiState = ItemUiState(details, isEntryValid = validate(details))
 }
 private fun validate(d: ItemDetails): Boolean =
 d.name.isNotBlank() &&
 nairaTextToKobo(d.price) != null &&
 (d.quantity.toIntOrNull() ?: -1) >= 0
 suspend fun saveItem() {
 if (validate(itemUiState.itemDetails)) {
 itemsRepository.insertItem(itemUiState.itemDetails.toItem())
 }
 }
}

Here the form state is held with Compose mutableStateOf inside the ViewModel (private set protects it from outside writes), a pattern the official codelab uses for text fields. StateFlow works equally well. saveItem is a suspend function the screen launches from rememberCoroutineScope (lesson 28), so the save is tied to the UI event.

Details: read, sell, edit, delete

class ItemDetailsViewModel(
 savedStateHandle: SavedStateHandle,
 private val itemsRepository: ItemsRepository
) : ViewModel() {
 private val itemId: Int = checkNotNull(savedStateHandle["itemId"])
 val uiState: StateFlow<ItemDetailsUiState> =
 itemsRepository.getItemStream(itemId)
 .filterNotNull()
 .map { ItemDetailsUiState(it.toItemDetails(), outOfStock = it.quantity <= 0) }
 .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), ItemDetailsUiState())
 suspend fun sellOne() {
 val item = uiState.value.itemDetails.toItem()
 if (item.quantity > 0) itemsRepository.updateItem(item.copy(quantity = item.quantity - 1))
 }
 suspend fun deleteItem() {
 itemsRepository.deleteItem(uiState.value.itemDetails.toItem())
 }
}
data class ItemDetailsUiState(
 val itemDetails: ItemDetails = ItemDetails(),
 val outOfStock: Boolean = true
)

savedStateHandle["itemId"] receives the route argument from navigation (lesson 26: type-safe routes put their arguments into the SavedStateHandle). filterNotNull() drops the null emitted after a delete, so the screen does not crash while navigating away. Tap Sell, and updateItem changes the row; the getItem Flow re-emits; the screen shows the new quantity. You wrote no refresh code.

Factory

Use the factory pattern from lesson 30 to build each ViewModel from InventoryApplication.container, with createSavedStateHandle() for the one needing a handle:

object AppViewModelProvider {
 val Factory = viewModelFactory {
 initializer { HomeViewModel(inventoryApplication().container.itemsRepository) }
 initializer { ItemEntryViewModel(inventoryApplication().container.itemsRepository) }
 initializer {
 ItemDetailsViewModel(
 this.createSavedStateHandle(),
 inventoryApplication().container.itemsRepository
 )
 }
 }
}
fun CreationExtras.inventoryApplication(): InventoryApplication =
 this[AndroidViewModel.APPLICATION_KEY] as InventoryApplication

(Imports: androidx.lifecycle.createSavedStateHandle, androidx.lifecycle.viewmodel.CreationExtras, androidx.lifecycle.AndroidViewModel.)

Seeing the screen

Build three screens following lessons 21 and 26: a LazyColumn for the home list with a + floating action button; a form with two OutlinedTextFields (set keyboardOptions for decimal and number keyboards) and a Save button enabled when isEntryValid; and a details screen with Sell, Edit and Delete buttons. Delete should ask for confirmation with an AlertDialog.

Run the app, add three items, then open View > Tool Windows > App Inspection and choose Database Inspector (lesson 44 covers the inspectors in depth). You can:

• See the items table and every row live.
• Run your own SQL (SELECT * FROM items WHERE quantity = 0).
• Edit a cell and watch the app's list update immediately, which proves the Flow wiring.

The Inspector works with debuggable builds running on an emulator or device that supports it. It is the fastest way to answer "is the problem in my query or in my UI?".

Suppose version 2 of your app adds a supplier column. Users already have a version 1 database on their phones. If you simply change the entity and bump version, Room refuses to open the old file ("a migration from 1 to 2 is required") because it cannot guess what to do with the existing data.

You have three options:

Always test migrations (Room provides a migration test helper that loads the exported schemas). A broken migration crashes the app at launch for every existing user, which is among the most painful bugs to ship. The exact API for migrations changed in Room 3 (migrations are suspend, working with SQLiteConnection instead of SupportSQLiteDatabase); follow the official migration guide for your Room version rather than copying from older articles.

A DAO test runs on a device or emulator (it needs a real SQLite) and uses an in-memory database that vanishes after the test:

// app/src/androidTest/.../ItemDaoTest.kt
package com.example.inventory
import android.content.Context
import androidx.room3.Room
import androidx.sqlite.driver.AndroidSQLiteDriver
import androidx.test.core.app.ApplicationProvider
import androidx.test.ext.junit.runners.AndroidJUnit4
import com.example.inventory.data.InventoryDatabase
import com.example.inventory.data.Item
import com.example.inventory.data.ItemDao
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.test.runTest
import org.junit.After
import org.junit.Assert.assertEquals
import org.junit.Before
import org.junit.Test
import org.junit.runner.RunWith
@RunWith(AndroidJUnit4::class)
class ItemDaoTest {
 private lateinit var db: InventoryDatabase
 private lateinit var dao: ItemDao
 @Before
 fun createDb() {
 val context = ApplicationProvider.getApplicationContext<Context>()
 db = Room.inMemoryDatabaseBuilder<InventoryDatabase>(context)
 .setDriver(AndroidSQLiteDriver())
 .build()
 dao = db.itemDao()
 }
 @After
 fun closeDb() = db.close()
 @Test
 fun insert_thenReadAll_returnsItemsSortedByName() = runTest {
 dao.insert(Item(name = "Rice", priceKobo = 5_000_000, quantity = 3))
 dao.insert(Item(name = "Beans", priceKobo = 2_500_000, quantity = 10))
 val names = dao.getAllItems().first().map { it.name }
 assertEquals(listOf("Beans", "Rice"), names)
 }
 @Test
 fun update_changesQuantity() = runTest {
 dao.insert(Item(name = "Garri", priceKobo = 100_000, quantity = 5))
 val saved = dao.getAllItems().first().single()
 dao.update(saved.copy(quantity = 4))
 assertEquals(4, dao.getItem(saved.id).first()?.quantity)
 }
}

The .first() operator takes one emission from the Flow and finishes, which gives a clean "read once" in a test. Test dependencies: androidTestImplementation entries for androidx.test.ext:junit, androidx.test:core and kotlinx-coroutines-test (look up current versions; the project template already includes the first). Room 2.x uses Room.inMemoryDatabaseBuilder(context, InventoryDatabase::class.java) and often .allowMainThreadQueries() for blocking tests.

Mistake #1: Creating the database more than once. What happens: wasted memory, and two instances that do not see each other's changes. The fix: one instance in the app container.

Mistake #2: Forgetting @PrimaryKey. Symptom: a build error saying the entity needs a primary key. The fix: add one, usually autoGenerate = true with a default of 0.

Mistake #3: Changing the schema without bumping the version. Symptom: a crash on launch with an integrity or identity-hash error. The fix: increase version and provide a migration. During early development, uninstall the app to clear the old database.

Mistake #4: fallbackToDestructiveMigration() on user data. What happens: all user data deleted on upgrade. The fix: write migrations for anything users created.

Mistake #5: Blocking DAO calls on the main thread (Room 2.x). Symptom: Cannot access database on the main thread. The fix: suspend or Flow. Do not use allowMainThreadQueries() outside tests.

Mistake #6: @Update on an item with the wrong id. What happens: nothing is updated. The fix: load the row first and use copy on it, so the id is preserved.

Mistake #7: Storing money in Double. What happens: rounding oddities. The fix: kobo as Long.

Mistake #8: Wrong KSP version. Symptom: a Gradle error mentioning an incompatible Kotlin version. The fix: use the KSP release whose version prefix matches your Kotlin version.

Mistake #9: Room 2.x and Room 3 imports mixed together. Symptom: unresolved references or ambiguous types. The fix: pick one version, use only its package (androidx.room. or androidx.room3.).

Mistake #10: Treating the Flow like a one-shot call. What happens: calling getAllItems() repeatedly, creating new collectors. The fix: build the Flow once in the ViewModel and expose it with stateIn.

Question 1. What are the three main Room components?

Question 2. Why does a DAO function returning Flow not need suspend?

Question 3. How does the UI update when a row is inserted from another screen?

Question 4. Why is fallbackToDestructiveMigration dangerous?

Question 5. Why store prices as whole kobo rather than Double?

Go deeper: official resources

• Android Basics with Compose, Unit 6, Pathway 2: Persist data with Room: the official pathway including the Inventory app and Bus Schedule practice.
• Room: save data in a local database
• Migrate from Room 2.x to Room 3.0
• Offline-first data layer