Introduction

The Room persistence library, part of Android Jetpack, acts as an abstraction layer over SQLite that provides compile-time query verification, seamless LiveData/Flow integration, and a clean API. Despite its convenience, many developers stumble by neglecting schema migrations, using blocking calls on the main thread, or mismanaging entities. This tutorial walks through the production-grade patterns that keep a Room-backed app reliable, testable, and performant.

Gradle Dependencies and Module Setup

Before defining any database classes, you must opt your module into the Room annotation processor and declare the runtime artifacts. Modern Android projects use KSP (Kotlin Symbol Processing) instead of the legacy kapt processor, which is significantly faster and fully Kotlin-first.

// build.gradle (app module)
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.ksp' version '2.0.21-1.0.28'
    id 'org.jetbrains.kotlin.android'
}

android {
    namespace = 'com.example.roombestpractices'
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = '17'
    }
}

dependencies {
    implementation 'androidx.room:room-runtime:2.6.1'
    implementation 'androidx.room:room-ktx:2.6.1'
    ksp 'androidx.room:room-compiler:2.6.1'
}

The room-ktx artifact is essential because it pulls in the Coroutines and Flow extensions, which allow DAOs to return Flow<List<T>> and suspend functions directly. Using KSP instead of kapt eliminates the annotation-processor round-trip overhead and avoids certain Kotlin-language edge cases that plagued the older processor. The compiler version should match your KSP plugin version exactly, or the symbol processing pipeline will fail silently at build time.

Defining @Entity Models and Primary Keys

Every table in Room maps to a Kotlin data class annotated with @Entity. Choosing the right primary key strategy is one of the most impactful decisions you will make, because it affects insertion performance, migration complexity, and even your choice between Int and Long columns.

import androidx.room.Entity
import androidx.room.PrimaryKey
import androidx.room.Index

@Entity(
    tableName = "users",
    indices = [Index(value = ["email"], unique = true)]
)
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0L,
    val email: String,
    val displayName: String,
    val createdAtMillis: Long
)

The indices array on the @Entity annotation is what enforces the unique constraint at the database level, not just in application code. That means a second insert with a duplicate email will throw a SQLiteConstraintException, giving you early failure instead of silent data corruption. Using autoGenerate = true on a Long primary key lets Room hand out monotonically increasing IDs; for high-concurrency apps you may prefer @PrimaryKey val id: String with a UUID generated in Kotlin, but that moves ID generation outside the database and loses SQLite's auto-increment optimization.

DAO Design with Suspend Functions and Flow

DAO interfaces are where Room generates its SQL at compile time. Declaring query methods as suspend functions is mandatory for mutating operations, while returning Flow<T> from selection queries gives you reactive, lifecycle-aware result streams.

import androidx.lifecycle.LiveData
import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import androidx.room.Update
import kotlinx.coroutines.flow.Flow

@Dao
interface UserDao {
    @Query("SELECT * FROM users ORDER BY createdAtMillis DESC")
    fun observeAll(): Flow<List<User>>

    @Query("SELECT * FROM users WHERE id = :userId")
    suspend fun getById(userId: Long): User?

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun upsert(user: User): Long

    @Update
    suspend fun update(user: User): Int

    @Query("DELETE FROM users WHERE id = :userId")
    suspend fun deleteById(userId: Long): Int
}

Each method maps directly to a single SQL statement that the Room compiler validates before the app even compiles. The onConflict = OnConflictStrategy.REPLACE policy on upsert means the database will atomically remove the old row and insert the new one when a primary-key collision occurs; this is cheaper than a manual two-step delete-then-insert. Because observeAll() returns a Flow, callers can collect it inside a lifecycleScope and receive every change automatically without manual invalidation.

Building the RoomDatabase Class

The database class is a singleton entry point that holds the schema, manages connection pooling, and exposes your DAOs. Declaring it as an abstract class that extends RoomDatabase is required so Room can generate the implementation at compile time.

import android.content.Context
import androidx.room.Database
import androidx.room.Room
import androidx.room.RoomDatabase
import androidx.sqlite.db.SupportSQLiteDatabase
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

@Database(
    entities = [User::class],
    version = 1,
    exportSchema = true
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao

    companion object {
        @Volatile
        private var INSTANCE: AppDatabase? = null

        fun getDatabase(context: Context, scope: CoroutineScope): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,
                    AppDatabase::class.java,
                    "app_database"
                )
                    .addCallback(object : RoomDatabase.Callback() {
                        override fun onOpen(db: SupportSQLiteDatabase) {
                            super.onOpen(db)
                            scope.launch(Dispatchers.IO) {
                                preloadSampleData(db)
                            }
                        }
                    })
                    .build()
                INSTANCE = instance
                instance
            }
        }

        private fun preloadSampleData(db: SupportSQLiteDatabase) {
            db.execSQL("INSERT OR IGNORE INTO users (id, email, displayName, createdAtMillis) VALUES (1, '[email protected]', 'Alice', 1700000000000)")
            db.execSQL("INSERT OR IGNORE INTO users (id, email, displayName, createdAtMillis) VALUES (2, '[email protected]', 'Bob', 1700100000000)")
        }
    }
}

The double-checked locking pattern inside companion object is deliberate: Room database creation is expensive and thread-safe initialization must avoid creating multiple instances under concurrency. Setting exportSchema = true writes a JSON schema snapshot into src/main/res/migration/ after each build, which is mandatory for later migration validation. The onOpen callback runs on the main thread by default, so the coroutine scoping ensures the seed data insert happens on Dispatchers.IO.

Type Converters for Non-Standard Columns

Room only understands types that map directly to SQLite columns (Integer, Real, Text, Blob). When your entity needs a Date, Enum, List<String>, or a custom data class, you must supply a TypeConverter to bridge the gap between the persisted representation and your Kotlin type.

import androidx.room.TypeConverter
import java.util.Date

class Converters {
    @TypeConverter
    fun fromTimestamp(value: Long?): Date? =
        value?.let { Date(it) }

    @TypeConverter
    fun dateToTimestamp(date: Date?): Long? =
        date?.time
}

The converter methods must be registered on the @Database annotation via converters = [Converters::class]; otherwise Room silently ignores them and throws a compilation error whenever it encounters an unconverted type in an entity field. Each converter pair must be bijective — converting a Date to a Long and back must always yield the same instant — because Room applies these conversions during both reads and writes, and a non-invertible converter produces subtly corrupted data.

Schema Migrations Across Database Versions

Migrations are the most commonly mishandled part of Room. Every time you increment version in @Database, you must provide a Migration object that describes how to transform the schema from the previous version to the new one; without it the app crashes with IllegalStateException on launch.

import androidx.room.migration.Migration
import androidx.sqlite.db.SupportSQLiteDatabase

val MIGRATION_1_2: Migration = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            """
            CREATE TABLE IF NOT EXISTS orders (
                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                userId INTEGER NOT NULL,
                totalCents INTEGER NOT NULL,
                status TEXT NOT NULL DEFAULT 'pending',
                createdAtMillis INTEGER NOT NULL,
                FOREIGN KEY(userId) REFERENCES users(id) ON DELETE CASCADE
            )
            """.trimIndent()
        )
        database.execSQL("CREATE INDEX IF NOT EXISTS idx_orders_user ON orders(userId)")
    }
}

The Migration constructor arguments define the transition boundary — this object handles upgrades from version 1 to version 2 only, and Room looks up the correct sequence of migrations to apply when your app ships version 3, 4, and beyond. Notice the ON DELETE CASCADE on the foreign key; SQLite enforces referential integrity only when foreignKeys is declared on the @Entity annotation alongside the raw DDL. After writing the migration, add it to the database builder with .addMigrations(MIGRATION_1_2) and run an instrumented test to verify the transition produces a consistent schema.

Testing with In-Memory Databases

Unit tests against a real file-backed database are slow and leak state across runs. The standard approach is to create an in-memory instance via Room.inMemoryDatabaseBuilder, which gives you a fresh isolated SQLite database for every test while preserving all compile-time query checks.

import androidx.room.Room
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationTestCase
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 UserDaoTest {

    private lateinit var db: AppDatabase
    private lateinit var userDao: UserDao

    @Before
    fun createDb() {
        db = Room.inMemoryDatabaseBuilder(
            InstrumentationTestCase().applicationContext,
            AppDatabase::class.java
        ).build()
        userDao = db.userDao()
    }

    @After
    fun closeDb() {
        db.close()
    }

    @Test
    fun insertAndGetById() = runTest {
        val user = User(email = "[email protected]", displayName = "Test User", createdAtMillis = 1000L)
        val id = userDao.upsert(user)
        val fetched = userDao.getById(id)
        assertEquals(user.email, fetched?.email)
        assertEquals(user.displayName, fetched?.displayName)
    }

    @Test
    fun flowEmitsInsertedUsers() = runTest {
        userDao.upsert(User("[email protected]", "A", 1L))
        userDao.upsert(User("[email protected]", "B", 2L))
        val users = userDao.observeAll().first()
        assertEquals(2, users.size)
        assertEquals("B", users[0].displayName)
    }
}

Because inMemoryDatabaseBuilder discards the database after each test method, assertions are completely independent and no tearDown cleanup of rows is necessary. The runTest coroutine dispatcher is required because suspend DAO methods must execute within a coroutine; without it the test framework would throw an IllegalStateException about missing coroutine context. For migration-specific tests, swap inMemoryDatabaseBuilder for Room.databaseBuilder pointing to a temporary file path so the schema-evolution path is exercised end to end.

Common Pitfalls

One of the most frequent mistakes is forgetting to annotate DAO methods with @Query, @Insert, or other Room annotations — unannotated methods are compiled away, causing silent compilation success with runtime crashes the first time the method is invoked. Another common error is calling suspend DAO functions from the main thread without a coroutine scope, which triggers a IllegalStateException because Room requires suspending execution on a background thread. Developers sometimes also forget to call db.close() in tests or in Application.onDestroy(), leaking native SQLite connections until the process terminates. Finally, omitting exportSchema = true prevents Room from storing schema snapshots, which makes it impossible to detect accidental schema changes that violate an existing migration.

Conclusion

Room's strength lies in its compile-time guarantees and tight integration with Kotlin coroutines and Flow. By structuring your entities with proper indexes, designing DAOs around suspend and reactive primitives, providing explicit type converters, and treating migrations as first-class artifacts with dedicated tests, you convert Room from a simple SQLite wrapper into a dependable persistence layer. The patterns in this tutorial are designed to scale: as your domain grows, add new @Entity classes and migrations, extend TypeConverters, and reuse the in-memory database test pattern to guard against regressions.