Modern Android applications often need to store data locally on a user’s device.

For example, an application may need to store:

• User information
• Products
• Orders
• Notes
• Messages
• Tasks
• Offline content
• Search history
• App settings
• Cached API responses

For simple key-value data, preferences or DataStore can be useful. But when an application needs to store and query structured data, a local database is often a better solution.

Room Database is one of the most popular database solutions for Android applications. It provides an abstraction layer over SQLite and makes database operations easier to implement using Kotlin.

In this complete guide, you’ll learn what Room Database is, how Room works, how to add Room to a Kotlin Android project, how to create entities, DAOs, and databases, how to perform CRUD operations, how to use Room with Kotlin Coroutines and Flow, and how to structure Room using Repository and ViewModel architecture.

---

What Is Room Database?

Room is a persistence library provided by Android Jetpack.

It provides an abstraction layer over SQLite while allowing developers to work with Kotlin classes and SQL queries.

Instead of directly managing SQLite APIs, you can define:

Entity
   ↓
DAO
   ↓
Room Database
   ↓
Application

Room handles much of the database implementation for you.

---

Why Use Room Database?

Direct SQLite APIs can require a significant amount of boilerplate code.

Room simplifies database development by providing:

• Compile-time SQL query verification
• Kotlin-friendly APIs
• Entity classes
• DAO interfaces
• Coroutine support
• Flow support
• Transaction support
• Migration support
• Integration with Android architecture components

For modern Android applications, Room is generally easier to maintain than working directly with SQLite APIs.

---

Room Database vs SQLite

Room does not replace SQLite itself.

Instead, Room works on top of SQLite.

Think of the relationship like this:

Your Kotlin Application
        ↓
      Room
        ↓
     SQLite
        ↓
 Local Database File

SQLite is the underlying database engine, while Room provides a developer-friendly abstraction layer.

---

How Room Database Works

Room primarily uses three important components:

1. Entity
2. DAO
3. Database

Together they create the Room architecture.

                Room Database
                     |
        +------------+------------+
        |            |            |
      Entity         DAO       Database
        |            |            |
        +------------+------------+
                     |
                 SQLite

Let’s understand each component.

---

1. Room Entity

An Entity represents a table in the database.

For example, suppose you want to store users.

You can create:

@Entity
data class User(
    @PrimaryKey
    val id: Int,
    val name: String,
    val email: String
)

Room will create a database table based on this class.

Conceptually:

User Entity
    ↓
users table

id | name | email

---

2. Room DAO

DAO stands for Data Access Object.

A DAO defines the operations that your application can perform on the database.

For example:

@Dao
interface UserDao {

    @Insert
    suspend fun insertUser(user: User)

    @Query("SELECT * FROM User")
    suspend fun getUsers(): List<User>
}

The DAO is responsible for database operations.

---

3. Room Database

The Room database class connects entities and DAOs together.

Example:

@Database(
    entities = [User::class],
    version = 1
)
abstract class AppDatabase : RoomDatabase() {

    abstract fun userDao(): UserDao
}

Now the architecture becomes:

User Entity
     ↓
 UserDao
     ↓
AppDatabase

---

Room Database Architecture

A typical Room setup looks like this:

              Android Application
                       |
                    ViewModel
                       |
                   Repository
                       |
                     DAO
                       |
                  Room Database
                       |
                    SQLite

This architecture separates UI logic from database logic.

---

Adding Room to a Kotlin Project

For a Kotlin Android project, add the Room dependencies to your Gradle configuration.

Depending on your project setup, Room can be configured using Kotlin’s annotation processing tooling.

A typical dependency setup includes:

dependencies {
    implementation("androidx.room:room-runtime:<version>")
    implementation("androidx.room:room-ktx:<version>")
    ksp("androidx.room:room-compiler:<version>")
}

Use a current Room version compatible with your Android Gradle Plugin and Kotlin setup.

---

What Is KSP?

KSP stands for Kotlin Symbol Processing.

Room uses code generation to create implementation classes based on your:

• Entities
• DAOs
• Database definitions

KSP allows Room to generate the required database code during compilation.

Your application code might define:

@Dao
interface UserDao

and Room generates the implementation behind the scenes.

---

Creating Your First Room Entity

Let’s create a simple User entity.

@Entity
data class User(

    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,

    val name: String,

    val email: String
)

Here:

@Entity

tells Room that the class represents a database table.

And:

@PrimaryKey

identifies the primary key.

---

What Is a Primary Key?

A primary key uniquely identifies a database record.

For example:

id | name
---|------
1  | John
2  | Sarah
3  | David

The id column uniquely identifies each user.

With Room:

@PrimaryKey
val id: Int

You can also allow Room to generate IDs automatically:

@PrimaryKey(autoGenerate = true)
val id: Int = 0

---

Room Table Names

By default, Room uses the entity class name as the table name.

You can specify a custom table name:

@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,

    val name: String,
    val email: String
)

Now the SQLite table will be:

users

---

Room Column Names

You can also specify a custom column name.

@Entity
data class User(

    @PrimaryKey
    val id: Int,

    @ColumnInfo(name = "full_name")
    val name: String,

    val email: String
)

The database will use:

id
full_name
email

---

Creating a DAO

Now create a DAO for the User entity.

@Dao
interface UserDao {

    @Insert
    suspend fun insertUser(user: User)

    @Query("SELECT * FROM users")
    suspend fun getUsers(): List<User>
}

The DAO contains database operations.

---

What Is @Dao?

The @Dao annotation tells Room that an interface or abstract class contains database access methods.

Common DAO annotations include:

@Insert
@Update
@Delete
@Query
@Upsert

---

Inserting Data With Room

Use @Insert to insert data.

@Insert
suspend fun insertUser(user: User)

Then:

val user = User(
    name = "John",
    email = "john@example.com"
)

userDao.insertUser(user)

Room generates the required SQL operation.

---

Inserting Multiple Records

You can insert multiple objects:

@Insert
suspend fun insertUsers(users: List<User>)

Then:

userDao.insertUsers(
    listOf(
        User(name = "John", email = "john@example.com"),
        User(name = "Sarah", email = "sarah@example.com"),
        User(name = "David", email = "david@example.com")
    )
)

---

Room @Query

The @Query annotation allows you to write SQL queries.

Example:

@Query("SELECT * FROM users")
suspend fun getUsers(): List<User>

Room checks the query during compilation.

This is one of the major benefits of Room.

---

Getting a Single User

You can query a specific record:

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

The :userId parameter is replaced with the method argument.

---

Querying by Email

@Query("SELECT * FROM users WHERE email = :email")
suspend fun getUserByEmail(
    email: String
): User?

This is useful for login or account-related operations.

---

Updating Data

Use @Update.

@Update
suspend fun updateUser(user: User)

For example:

val updatedUser = user.copy(
    name = "John Smith"
)

userDao.updateUser(updatedUser)

---

Deleting Data

Use @Delete.

@Delete
suspend fun deleteUser(user: User)

You can also use a custom query:

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

---

Room CRUD Operations

CRUD means:

Create
Read
Update
Delete

In Room:

Create → @Insert
Read   → @Query
Update → @Update / @Query
Delete → @Delete / @Query

These operations form the foundation of most local database applications.

---

Using Room With Coroutines

Room works well with Kotlin Coroutines.

Instead of performing database work directly on the UI thread, use suspend functions.

Example:

@Query("SELECT * FROM users")
suspend fun getUsers(): List<User>

Then call it from a coroutine:

viewModelScope.launch {
    val users = userDao.getUsers()
}

This keeps asynchronous database operations separate from UI rendering.

---

Why Use suspend With Room?

Database operations can take time.

For example:

Application
    ↓
Database Query
    ↓
Disk Operation
    ↓
Result

A suspend function allows the operation to work with Kotlin’s coroutine model without blocking the caller unnecessarily.

---

Room With Flow

One of Room’s most useful features is its integration with Kotlin Flow.

Instead of:

@Query("SELECT * FROM users")
suspend fun getUsers(): List<User>

you can expose:

@Query("SELECT * FROM users")
fun observeUsers(): Flow<List<User>>

Now Room can emit updated results when the observed database data changes.

---

Room + Flow Architecture

Database
   ↓
 Room
   ↓
 Flow<List<User>>
   ↓
Repository
   ↓
ViewModel
   ↓
UI

This is extremely useful for reactive applications.

---

Example: Observing Users

DAO:

@Query("SELECT * FROM users")
fun observeUsers(): Flow<List<User>>

Repository:

class UserRepository(
    private val userDao: UserDao
) {

    fun observeUsers(): Flow<List<User>> {
        return userDao.observeUsers()
    }
}

ViewModel:

class UserViewModel(
    private val repository: UserRepository
) : ViewModel() {

    val users =
        repository.observeUsers()
}

The UI can observe the Flow.

---

Room With StateFlow

You can convert a Room Flow into StateFlow in a ViewModel.

For example:

val users =
    repository.observeUsers()
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5000),
            initialValue = emptyList()
        )

Now the UI can observe a state stream.

---

Room With Jetpack Compose

In a Compose application, you might have:

val users by viewModel.users
    .collectAsStateWithLifecycle()

Then:

LazyColumn {
    items(users) { user ->
        Text(user.name)
    }
}

When the Room database changes, the Flow emits a new list and Compose can update the UI.

---

Room Repository Pattern

A Repository acts as an abstraction between the ViewModel and database.

Example:

class UserRepository(
    private val userDao: UserDao
) {

    fun observeUsers(): Flow<List<User>> {
        return userDao.observeUsers()
    }

    suspend fun insertUser(user: User) {
        userDao.insertUser(user)
    }

    suspend fun deleteUser(user: User) {
        userDao.deleteUser(user)
    }
}

The ViewModel doesn’t need to know how Room works internally.

---

Why Use a Repository?

Without a Repository:

UI
 ↓
ViewModel
 ↓
DAO

With a Repository:

UI
 ↓
ViewModel
 ↓
Repository
 ↓
DAO
 ↓
Room

The Repository can later combine multiple data sources.

For example:

Repository
   ├── Room
   ├── REST API
   └── Cache

This makes the application architecture more flexible.

---

Creating the Room Database

Now let’s create the database class.

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

    abstract fun userDao(): UserDao
}

This tells Room:

• Which entities belong to the database
• The database version
• Which DAO is available

---

Building the Database Instance

You can create the database using Room.databaseBuilder().

val database =
    Room.databaseBuilder(
        context,
        AppDatabase::class.java,
        "app_database"
    ).build()

Then access the DAO:

val userDao = database.userDao()

---

Avoid Creating Multiple Database Instances

A Room database is generally expensive enough that you should avoid repeatedly creating new instances.

A common approach is to keep one database instance for the application process.

For example:

@Database(...)
abstract class AppDatabase : RoomDatabase() {

    abstract fun userDao(): UserDao

    companion object {

        @Volatile
        private var INSTANCE: AppDatabase? = null

        fun getDatabase(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {

                val instance =
                    Room.databaseBuilder(
                        context.applicationContext,
                        AppDatabase::class.java,
                        "app_database"
                    ).build()

                INSTANCE = instance
                instance
            }
        }
    }
}

In larger applications, dependency injection frameworks can manage this lifecycle for you.

---

Room Singleton Pattern

The basic idea is:

Application
     ↓
Single Room Instance
     ↓
DAOs

This avoids unnecessarily creating multiple database objects.

---

Room Relationships

Real applications often have related tables.

For example:

User
 |
 +--- Orders
       |
       +--- Products

Room supports relationships between entities.

Common relationships include:

• One-to-one
• One-to-many
• Many-to-many

---

One-to-Many Relationship

Suppose one user can have multiple orders.

User
 |
 +--- Order 1
 |
 +--- Order 2
 |
 +--- Order 3

You can represent this using Room relationship classes.

For example:

data class UserWithOrders(
    @Embedded
    val user: User,

    @Relation(
        parentColumn = "id",
        entityColumn = "userId"
    )
    val orders: List<Order>
)

Then query:

@Transaction
@Query("SELECT * FROM users")
suspend fun getUsersWithOrders(): List<UserWithOrders>

---

Why Use @Transaction?

When multiple database operations need to be treated as one logical operation, use a transaction.

Example:

@Transaction
@Query("SELECT * FROM users")
suspend fun getUsersWithOrders(): List<UserWithOrders>

This helps ensure the related operations are handled consistently.

---

Many-to-Many Relationships

Suppose:

Students ↔ Courses

A student can have multiple courses, and a course can have multiple students.

This is a many-to-many relationship.

Room can represent this using a junction table.

Conceptually:

Students
    ↓
StudentCourse
    ↑
Courses

---

Room Database Migrations

As your application grows, the database structure may change.

Version 1:

users
------
id
name

Later, you add:

email

Now the database schema has changed.

You should handle this with a migration.

---

Why Are Migrations Important?

Without proper migration handling, existing users may lose locally stored data when the application is updated.

For example:

App Version 1
      ↓
Database Version 1
      ↓
App Update
      ↓
Database Version 2

Room needs to know how to move from version 1 to version 2.

---

Creating a Migration

For example:

val MIGRATION_1_2 =
    object : Migration(1, 2) {

        override fun migrate(
            database: SupportSQLiteDatabase
        ) {
            database.execSQL(
                "ALTER TABLE users ADD COLUMN email TEXT"
            )
        }
    }

Then:

Room.databaseBuilder(
    context,
    AppDatabase::class.java,
    "app_database"
)
    .addMigrations(MIGRATION_1_2)
    .build()

---

Room Database Version

Your database class contains a version:

@Database(
    entities = [User::class],
    version = 2
)

When the schema changes, update the database version and provide the required migration.

---

Auto Migration

Room also supports automatic migrations for certain schema changes.

For example:

@Database(
    entities = [User::class],
    version = 2,
    autoMigrations = [
        AutoMigration(from = 1, to = 2)
    ]
)
abstract class AppDatabase : RoomDatabase()

Automatic migrations are convenient for supported schema changes, but more complex changes may require a manual migration.

---

Room Type Converters

SQLite supports a limited set of basic data types.

But your Kotlin model might contain:

Date
Enum
List
Custom Object

Room can use TypeConverters to convert these values.

---

Example: Enum Type Converter

Suppose:

enum class UserRole {
    ADMIN,
    USER
}

You can create a converter:

class Converters {

    @TypeConverter
    fun fromUserRole(role: UserRole): String {
        return role.name
    }

    @TypeConverter
    fun toUserRole(value: String): UserRole {
        return UserRole.valueOf(value)
    }
}

Then register it with Room.

@TypeConverters(Converters::class)
@Database(
    entities = [User::class],
    version = 1
)
abstract class AppDatabase : RoomDatabase()

---

Room Indexes

Indexes can improve query performance for frequently searched columns.

For example:

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

    val name: String,

    val email: String
)

This can also enforce uniqueness for the indexed column.

---

Room Unique Constraints

If emails should be unique:

indices = [
    Index(
        value = ["email"],
        unique = true
    )
]

This helps prevent duplicate email records at the database level.

---

Room @Upsert

For applications that need insert-or-update behavior, Room provides @Upsert.

Example:

@Upsert
suspend fun saveUser(user: User)

This is useful when you don’t want to manually determine whether a record already exists before saving it.

---

Room DAO Example

A more complete DAO might look like:

@Dao
interface UserDao {

    @Insert
    suspend fun insertUser(user: User)

    @Upsert
    suspend fun saveUser(user: User)

    @Update
    suspend fun updateUser(user: User)

    @Delete
    suspend fun deleteUser(user: User)

    @Query("SELECT * FROM users")
    fun observeUsers(): Flow<List<User>>

    @Query(
        "SELECT * FROM users WHERE id = :id"
    )
    suspend fun getUserById(id: Int): User?

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

---

Room and Clean Architecture

Room fits well into a Clean Architecture structure.

A typical project can be organized like:

data/
    local/
        database/
            AppDatabase.kt
            UserDao.kt
            UserEntity.kt

    repository/
        UserRepositoryImpl.kt

domain/
    model/
        User.kt

    repository/
        UserRepository.kt

presentation/
    user/
        UserViewModel.kt
        UserScreen.kt

The exact folder structure depends on your project, but keeping database-specific code in the data layer helps maintain separation.

---

Entity vs Domain Model

A useful architecture practice is to distinguish database entities from domain models when your application becomes more complex.

For example:

@Entity
data class UserEntity(
    val id: Int,
    val name: String,
    val email: String
)

Domain model:

data class User(
    val id: Int,
    val name: String,
    val email: String
)

You can map between them:

fun UserEntity.toDomain(): User {
    return User(
        id = id,
        name = name,
        email = email
    )
}

This prevents Room-specific details from leaking into your domain layer.

---

Room + API + Repository

A common modern application uses both a remote API and a local Room database.

Architecture:

             API
              ↓
         Repository
          ↙       ↘
       Room       Network
        ↓           ↓
      Local      Remote
        ↓           ↓
        └─────┬─────┘
              ↓
             Flow
              ↓
          ViewModel
              ↓
              UI

For offline-first applications, the repository can use Room as the local source of truth while synchronizing data with the server.

---

Offline-First Architecture With Room

An offline-first approach can work like:

Network API
     ↓
Repository
     ↓
Room Database
     ↓
Flow
     ↓
UI

The application displays locally stored data and updates the database when fresh server data is available.

This can make applications more resilient when network connectivity is poor or unavailable.

---

Room Database Testing

Database code should be tested.

You can test:

• Insert operations
• Query operations
• Update operations
• Delete operations
• Relationships
• Migrations
• Constraints

For example:

Create Database
      ↓
Insert User
      ↓
Query User
      ↓
Verify Result

Testing database operations helps catch incorrect SQL and schema problems early.

---

Common Room Database Mistakes

1. Performing Database Work on the Main Thread

Avoid blocking the UI thread with database operations.

Use suspend functions and appropriate coroutine architecture.

---

2. Creating Multiple Database Instances

Prefer a single managed database instance per application process.

---

3. Ignoring Migrations

When your schema changes, handle the migration properly.

---

4. Putting Database Logic Directly in UI

Avoid:

UI
 ↓
DAO

Prefer:

UI
 ↓
ViewModel
 ↓
Repository
 ↓
DAO

---

5. Using Large Unoptimized Queries

Be careful with queries that return huge amounts of data.

Use:

• Filtering
• Pagination
• Appropriate indexes
• Specific columns when appropriate

---

6. Not Using Flow for Observable Data

If the UI needs continuous updates from the database, a Flow-based DAO query can be much more useful than repeatedly requesting the entire dataset.

---

Room Database Best Practices

Use meaningful table and column names

Good naming makes your database easier to understand.

Keep DAOs focused

Avoid putting unrelated database operations into one giant DAO.

Use repositories

Repositories provide a clean abstraction between your data and presentation layers.

Use Flow for reactive database data

This works particularly well with modern Android architecture.

Use migrations

Never assume users can simply recreate the database after an application update.

Add indexes where needed

Indexes can improve frequently executed queries, but don’t add them blindly because they also have storage and write-performance costs.

Use transactions for related operations

Transactions help maintain database consistency.

Test migrations

A migration that works in development but fails on an existing user’s database can cause serious problems.

---

Complete Room Example

Let’s combine the important pieces.

Entity

@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,

    val name: String,
    val email: String
)

DAO

@Dao
interface UserDao {

    @Insert
    suspend fun insert(user: User)

    @Delete
    suspend fun delete(user: User)

    @Query("SELECT * FROM users")
    fun observeUsers(): Flow<List<User>>

    @Query(
        "SELECT * FROM users WHERE id = :id"
    )
    suspend fun getUser(id: Int): User?
}

Database

@Database(
    entities = [User::class],
    version = 1
)
abstract class AppDatabase : RoomDatabase() {

    abstract fun userDao(): UserDao
}

Repository

class UserRepository(
    private val userDao: UserDao
) {

    val users: Flow<List<User>> =
        userDao.observeUsers()

    suspend fun addUser(user: User) {
        userDao.insert(user)
    }

    suspend fun deleteUser(user: User) {
        userDao.delete(user)
    }
}

ViewModel

class UserViewModel(
    private val repository: UserRepository
) : ViewModel() {

    val users =
        repository.users.stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5000),
            initialValue = emptyList()
        )

    fun addUser(user: User) {
        viewModelScope.launch {
            repository.addUser(user)
        }
    }

    fun deleteUser(user: User) {
        viewModelScope.launch {
            repository.deleteUser(user)
        }
    }
}

This gives you a complete basic architecture:

UI
 ↓
ViewModel
 ↓
Repository
 ↓
DAO
 ↓
Room
 ↓
SQLite

---

Frequently Asked Questions

What is Room Database in Kotlin?

Room is an Android Jetpack persistence library that provides an abstraction layer over SQLite and makes local database operations easier to implement using Kotlin.

Is Room a database?

Room itself is not the underlying database engine. It is a persistence library that works with SQLite.

Why use Room instead of SQLite?

Room reduces boilerplate, provides compile-time query verification, integrates with Kotlin Coroutines and Flow, and works well with modern Android architecture.

Is Room better than SQLite?

For most modern Android applications, Room provides a more convenient and maintainable development experience than using SQLite APIs directly. SQLite remains the underlying database engine.

Can Room work with Kotlin Coroutines?

Yes. Room supports suspend DAO methods for asynchronous database operations.

Can Room work with Kotlin Flow?

Yes. Room can return Flow from DAO queries, allowing applications to observe database changes reactively.

Can Room be used with Jetpack Compose?

Yes. Room, Flow, ViewModel, and Jetpack Compose work well together for reactive Android applications.

Does Room support migrations?

Yes. Room supports both manual migrations and automatic migrations for supported schema changes.

Does Room support relationships?

Yes. Room supports one-to-one, one-to-many, and many-to-many relationships.

What is a DAO in Room?

DAO stands for Data Access Object. It defines the database operations your application can perform.

What is an Entity in Room?

An Entity is a Kotlin class that represents a database table.

What is @Database in Room?

@Database marks an abstract class as the Room database and defines the entities, database version, and configuration.

What is KSP in Room?

KSP, or Kotlin Symbol Processing, allows Room to generate implementation code during compilation based on your database definitions.

Can Room store API data?

Yes. A common architecture is to fetch data from an API, store it in Room, and expose the local database data to the UI through Flow.

---

Conclusion

Room Database is an important technology for Android developers who need reliable local data storage.

It provides a clean Kotlin-friendly layer over SQLite and works especially well with modern Android architecture.

The most important Room concepts to remember are:

Entity
→ Represents a database table

DAO
→ Defines database operations

RoomDatabase
→ Connects entities and DAOs

@Insert
→ Adds data

@Query
→ Reads or customizes data

@Update
→ Updates data

@Delete
→ Deletes data

@Upsert
→ Inserts or updates data

Flow
→ Observes database changes

Migration
→ Updates database schema safely

TypeConverter
→ Converts unsupported/custom types

Repository
→ Separates data access from ViewModel

A modern Kotlin Android application commonly follows:

             UI
              ↓
          ViewModel
              ↓
          Repository
              ↓
             DAO
              ↓
            Room
              ↓
           SQLite

When combined with Kotlin Coroutines, Flow, Jetpack Compose, and a Repository-based architecture, Room provides a powerful foundation for building applications that need local persistence, reactive data, and offline capabilities.

For beginners learning Android development with Kotlin, understanding Room + DAO + Entity + Flow + Repository is an important step toward building production-ready applications.