Let’s dive into what @RawQuery is, when it shines and shuns.

What is @RawQuery?

@RawQuery allows you to execute SQL statements that aren’t validated at compile time. Unlike @Query, which Room parses and validates during compilation, raw queries are evaluated at runtime.

You typically use @RawQuery with either SupportSQLiteQuery (for fully dynamic queries) or plain String (though the latter is limited and discouraged).

@Dao
interface ProductDao {

    @RawQuery 
    suspend fun getProductsWithRawQuery(query: SupportSQLiteQuery): List<Product>


    // This will be called from the repository
    @Transaction
    suspend fun getProductsAbovePrice(minPrice: Int): List<Product> {
    val query = SimpleSQLiteQuery(
        "SELECT * FROM products WHERE price > ?",
        arrayOf(minPrice)
    )
    return productDao.getProductsWithRawQuery(query)
    }
}

✅ When Should You Use @RawQuery?

Despite its risks, there are legitimate use cases for @RawQuery which come handy when the app is completely offline and need to do operations similar to server with available data for example sorting, filtering and searching etc.

There are some cases where you need advanced joins, unions, subqueries Room’s @Query might fall short an example i can think of are expense list screen where you need to get associated budgets,tags, users who created and approved them, etc getting this merged data specific filter and sort type will be extremely hard with conventional methods in cases like these @RawQuery are a boon.

This is one of my dao’s functions that is triggered when the there applies a filter, since there was no network i apply the filter and show the available data assuming the user already knows he is in offline mode,we have an indicator that should handle conveying of the message. So take a look and the params and tell me can we acheve this using conventional method faster than this ? i don’t think so but do share your views.

Lets check out my code for

 @RawQuery // Query runner
    suspend fun getExpensesWithParamsQueryRunner(query: SupportSQLiteQuery): List<LocalExpenseWithDetails>

 @Transaction // this will be called as a fallback option when offline
    suspend fun getExpensesWithParams(
        type: String?,
        budgetId: Long?,
        sessionId: Long?,
        filterParam: FilterParams,
        sortParam: SortParam,
        searchQuery: String?,
        page: Int
    ): List<LocalExpenseWithDetails> {
        val typeId = if (type != null && type != BaseExpenseType.ALL) getExpenseTypeWithName(type.serverKey) else null
        return getExpensesWithParamsQueryRunner(
            query = getExpenseQuery( // query generator
                typeId = typeId,
                budgetId = budgetId,
                sessionId = sessionId,
                filterParam = filterParam,
                sortParam = sortParam,
                search = searchQuery,
                page = page
            )
        )
    }

3. Performance Testing / Debugging During development, you might want to test different raw SQL statements quickly without baking them into DAOs.

⚠️ When NOT to Use @RawQuery

Just because you can doesn’t mean you should. Raw queries come with trade-offs:

• ❌ No Compile-Time Safety

Room won’t validate your SQL. Typos, wrong column names, or invalid SQL will only fail at runtime – often with vague errors.

• ❌ No Type Inference

Unlike @Query, Room won’t know what result type to expect unless you specify it manually and correctly.

• ❌ Risk of SQL Injection If you’re concatenating SQL strings, you open yourself to SQL injection vulnerabilities. Always use parameterized queries or filter the vulnerable queries.

// Bad ❌
val query = SimpleSQLiteQuery("SELECT * FROM products WHERE name = '$name'")

// Good ✅
val query = SimpleSQLiteQuery("SELECT * FROM products WHERE name = ?", arrayOf(name))

📋 Tips for Safely Using Raw Queries

• ✅ Always use SimpleSQLiteQuery with parameterized arguments.
• ✅ Keep the query logic isolated and well-documented.
• ✅ Prefer @Query whenever possible.
• ✅ Avoid user-generated input directly in SQL strings.
• ✅ Write tests to validate dynamic query paths.

🚫 Anti-Patterns to Avoid

• ❌ Using raw queries as your primary query method.
• ❌ Skipping query reuse – dynamic doesn’t mean you can’t structure it.
• ❌ Using @RawQuery when @Query or DAO methods would suffice.
• ❌ Ignoring test coverage for raw query logic.

I’ve even created my own query builder to simplify this process in my codebase. Whether you should use it or not depends on your needs, but I’m sharing it just so you know it exists because it was extremely useful for me. The code for my query builder can be found here: CustomQueryBuilder

🚀 Conclusion

@RawQuery is the escape hatch when Room’s abstraction becomes a cage. Use it when needed, but use it wisely. Think of it like the goto statement of Room – powerful but potentially dangerous if overused or misused.

In most offline-first app cases, well-structured DAOs using Room’s annotations will suffice. But in edge cases where flexibility is key, @RawQuery gives you that last-mile control.

Next up, we’ll explore Query Optimization Tips to keep your Offline-First App lightning fast, even at scale.

Next we will explore Data Access Objects, Stay tuned for the next article in this series! 🚀

Final Thoughts

Raw queries are sharp tools — excellent in skilled hands, but risky for the unprepared. If you’ve got a use case or edge case where @RawQuery saved your app or made something possible, I’d love to hear it!

Feel free to connect and share your stories: 📩 Email
🌍 Website
💫 LinkedIn-Post for comments and feedbacks

🔖 Previous Article in this Series 🚀 Stay tuned for Part 7! 🚀

What is a DAO?

A DAO is an interface annotated with @Dao that defines methods for interacting with the database. The Room compiler generates the necessary implementation for these interfaces and its methods, which enables us to access the database efficient and type safe.

A typical DAO will look simar as the code below:

@Dao
interface ProductDao {

 @Query("SELECT * FROM products")
 suspend fun getAllProducts(): List<Product>

 @Query("SELECT * FROM products WHERE id = :productId")
 suspend fun getProductById(productId: Long): Product?

 @Insert
 suspend fun insertProduct(product: Product)

 @Insert
 suspend fun insertProducts(products: List<Product>)
    
 @Update
 suspend fun updateProduct(product: Product)

 @Delete
 suspend fun deleteProduct(product: Product)

 @Upsert
 suspend fun upsertProduct(product: Product)
}

While the @Dao interface is created by the developer the instance/Implementation of the DAO’s are created by the compiler when the Database is created and the generated implementation file can be looked at the following path:

app/build/generated/source/kapt/debug/YOUR_PACKAGE_NAME/database/ProductDao_Impl.java

The file will contain the instance with impl as post fix and all the corresponding functions will have its own implementation accessing the SQLLite Database for example the select query annotated with @Query on the above DAO will generate an implementation code that is shared below, if you are to use SQLLite Directly this is the code you would have to write manually for each query:

The implementation of select query will look like this:

@Override
public Object getAllProducts(Continuation<? super List<Product>> continuation) {
    final String _sql = "SELECT * FROM products";
    final RoomSQLiteQuery _statement = RoomSQLiteQuery.acquire(_sql, 0);
    return CoroutinesRoom.execute(__db, false, continuation, new Callable<List<Product>>() {
 @Override
        public List<Product> call() throws Exception {
            Cursor _cursor = DBUtil.query(__db, _statement, false, null);
            try {
                List<Product> _result = new ArrayList<>();
                while (_cursor.moveToNext()) {
                    Product _item = new Product();
                    _item.id = _cursor.getLong(_cursor.getColumnIndexOrThrow("id"));
                    _item.name = _cursor.getString(_cursor.getColumnIndexOrThrow("name"));
                    _item.price = _cursor.getFloat(_cursor.getColumnIndexOrThrow("price"));
                    _result.add(_item);
 }
                return _result;
 } finally {
                _cursor.close();
                _statement.release();
 }
 }
 });
}

Isn’t it so nice how instead of writing 24 lines we just have to write 1

🙏 Thank You, Android and Google Team for making this extremely robust and performant.

Now that we got an intro on Dao and what happens behind the scenes, let’s go through the supported query annotations.

Supported Query Annotations

In the previous section of DAO example code, you might have noticed the annotations (@Insert,@Delete…) on each functions, these annotations help the compiler to generate query object on your behalf so we can smoothly interact with the database, Let’s go through each of them to understand how and when to use them effectively.

@Insert - Insert Data into the Database

Used for inserting single or multiple entries to a table, this will skip validation of checking if a duplicate entry with the same primary id exists, so it’s faster for insertion when you are clear that duplicate entries are impossible. In case you inset a duplicate entry the app will crash with the exception primary key already exists.

Here is an example of how the @Insert can be used:

...
 //Inserting single item
 @Insert(onConflict = OnConflictStrategy.REPLACE)
 suspend fun insertProduct(product: Product)     
 
 //Inserting multiple items
 @Insert
 suspend fun insertProducts(products: List<Product>)     
...

Conflict Strategy

Defining the conflict strategy on the query tells the room how to handle the conflict effectively by default it NONE:

• NONE: Default strategy when you insert duplicate it crashes the app.
• REPLACE: Keep the old data and ignore the new data.
• ABORT: Aborts the transaction entirely so none of the entries will be updated.
• IGNORE: Skip the entry and proceed to next

You can set your preference as per your requirement, but if you want the behavior of REPLACE hold on there is another annotation that we will learn about soon that is a better option.

⚠️ Beware: inserting duplicate entries will crash the app if you don’t provide a conflict strategy.

@Update - Modify Existing Data

Used for updating all columns of an existing row where the primary key matches, If the table does not contain a matching primary key, the update fails silently (no error or no exception) but the unmatched entries remain unchanged (they are not inserted or modified).

Like the @insert you can @update single or multiple entries, a sample code will look something like this:

...
 //Updating single item
 @Update
 suspend fun updateProduct(product: Product)   
 
 //Updating multiple items
 @Update
 suspend fun updateProducts(products: List<Product>)     
...

The update overrides the provided value to matched entries so if you accidentally provide a null value, that is exactly what the matched row’s column will be, for example, if you want to mark the product as sold-out you will think you have to send only a product object with id and the sold value but if you do that all other values like name, date, and other values will be set as null so ensure you provide all values.

⚠️ You are overriding all values, so ensure you provide all values in each entry.
⚠️ Unmatched rows will not be inserted, no errors or exceptions will be thrown

@Upsert - Insert or Update in One Call

@Upsert is a combination of @Insert and @Update, if the entry matches the primary-key it updates them, otherwise it inserts them smoothly, you could use @Insert with REPLACE if your table has no primary key otherwise this is better.

This is an example of how the ``@Upsert` will be used in a dao

// upsert single item
@Upsert
suspend fun upsertProduct(product: Product)

// upsert bulk Item
@Upsert
suspend fun upsertProducts(products: List<Product>)

One thing to note is that the conflict is handled only for the primary key, if your table has other columns that are set as unique the upsert may still fail if that rule is ever broken due to new data.

⚠️ Requires the primary key
⚠️ If your table has unique constraints on other columns, @Upsert may still fail.

@Delete - Remove Entries from the Database

Enables you to delete single and multiple entities blissfully, if the row does not exist it fails silently which means that the entries that exist will be deleted and the other will not since it does not exist, here is how typical delete functions will look like:

// delete single item
@Delete
suspend fun deleteProduct(product: Product)

// delete bulk Item
@Delete
suspend fun deleteProducts(products: List<Product>)

I don’t like to pass the entire entity for deletions so I prefer to use @Query for it so I can just pass the primary keys for deletion, but for simplicity, you can use the @Delete as well.

@Query - The Most Powerful Annotation

The @Query Swiss knife allows you to write custom SQL queries to interact with your database. It provides more flexibility than other annotations (@Insert, @Update, @Delete) and is essential for performing simple/complex operations depending on our use cases.

...
// bulk get
@Query("SELECT * FROM products")
suspend fun getAllProducts(): List<Product>

// single get 
@Query("SELECT * FROM products WHERE id = :productId")
suspend fun getProductById(productId: Long): Product?

// search Query
@Query("SELECT * FROM products WHERE name LIKE '%' || :searchQuery || '%'")
suspend fun searchProducts(searchQuery: String): List<Product>

// deleting item with ID
@Query("DELETE FROM products WHERE id = :productId")
suspend fun deleteProductById(productId: Long)

// delete multiple items
@Query("DELETE FROM products WHERE id IN (:productIds)")
suspend fun deleteProductById(productIds: List<Long>)

// deleting all entries (truncates)
@Query("DELETE FROM products")
suspend fun deleteAllProducts()
...

Swiss Knife it is, you can do all kinds of operations with it, its gives us more flexibility but as we know “With Great Power comes to Great Responsibility”. Although @Query is powerful, it can fail in various ways due to syntax errors, missing data, type mismatches, database constraints, etc.. so use it cautiously and expect exceptions and app crashes.

@RawQuery - Fully Dynamic SQL Execution

The @RawQuery annotation in Room allows you to write and execute fully dynamic SQL queries, will will explore this later in this series it breaks the simplicity boundary because there is no compile-time safety on this.

🚀 Conclusion

Data Access Objects (DAOs) are the backbone of efficient database operations in Room. They provide a clean, structured way to interact with your database while leveraging compile-time safety and reducing boilerplate SQL code. With annotations like @Insert, @Update, @Delete, @Upsert, and @Query, DAOs make it easier to perform CRUD operations while maintaining performance and maintainability.

By using DAOs, you ensure that your Offline-First App has a seamless data layer, enabling a smooth and efficient user experience.

Next, we will discuss about @RawQuery and its pro’s and cons…

Final Thoughts

This is my journey in building an offline-first app. I’d love to hear your feedback, suggestions, or questions!

Feel free to connect with me on:
📩 Email
🌍 Website
💫 LinkedIn-Post for comments and feedbacks

🔖 Previous Article in this Series 🚀 Stay tuned for Part 6! 🚀

🔖 Next Article in this Series

Entities are the foundation of Room—they define how your data is stored in the database. Properly structuring your entity ensures efficient querying, maintainability, and scalability. Let’s break it down! 🛠️

🏗️ What is an Entity?

An Entity in Room represents a table in the database. Each instance of the entity corresponds to a row in the table, Room generates corresponding SQL table schema based on how you create an entity class.

Defining an Entity:

@Entity
data class LocalHabitTracker(
    @PrimaryKey(autoGenerate = true) val id: Long,
    val associatedHabitId: Long,
    val positionX: Int,
    val positionY: Int,
    val note: String
)

Breaking It Down:

• @Entity tells Room that this class is a database table.
• @PrimaryKey is used to uniquely identify each row.
• autoGenerate = true ensures Room generates unique IDs automatically.
• @Ignore → Excludes a field from being stored in the database.

Before we procced further, Lets check out the sql query generated by the room

CREATE TABLE LocalHabitTracker (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    associatedHabitId INTEGER NOT NULL,
    positionX INTEGER NOT NULL,
    positionY INTEGER NOT NULL,
    note TEXT NOT NULL
);

Since its a simple entity it might look workable but think of adding indexes, relations and other complicated relations it can quickly get complicated and prone errors. That being said this is just to show you how room is doing most of the heavy lifting for you, lets move on to customizing our entities.

🔄 Customizing Entities

Room provides several ways to customize entities to fit your data structure requirements. Let’s explore these!

1️⃣ Custom Table and Column Names

By default, Room uses the class name as the table name and variable names as column names. You can override this using annotations:

@Entity(tableName = "habit_tracker")
data class LocalHabitTracker(
    @PrimaryKey(autoGenerate = true) val id: Long,
    @ColumnInfo(name = "habit_id") val associatedHabitId: Long,
    @ColumnInfo(name = "pos_x") val positionX: Int,
    @ColumnInfo(name = "pos_y") val positionY: Int,
    val note: String
)

• tableName changes the SQL table name while keeping the DataClass name as per your requiremnt.
• @ColumnInfo(name = “custom_name”) changes the column name in the table.

⚠️ These customizations are for the DataBase Tables which means when writing the query you must use the customized name for the query to work properly.

This is extremely useful when you want to Name your tables and columns differently, in kotlin we use camelcase but on sql its common to use underscore to split worlds like habit_tracker instead of LocalHabitTracker it simplifies the query and expedites debugging process.

Using custom name for table and column is optional so if you are comfortable with the existing name you can use just that, next up lets see how can we ensure the entities can be indexed faster.

2️⃣ Indexing for Faster Queries

Indexes speed up query performance, especially for large datasets. Use @Index for frequently queried columns, for example here the associated_habit_id will be used most frequently by me in different queries so i am adding indices property on the @Table annotation, here is an example:

@Entity(
    tableName = "habit_tracker",
    indices = [Index(value = ["associated_habit_id"])]
)
data class LocalHabitTracker(
    @PrimaryKey(autoGenerate = true) val id: Long,
    @ColumnInfo(name = "associated_habit_id")val associatedHabitId: Long,
    val positionX: Int,
    val positionY: Int,
    val note: String
)

• Indexing habit_id speeds up lookup queries on this column.

When Should You Use an Index?

✅ Use indexing if:

• The column is used frequently in WHERE, JOIN, or ORDER BY.
• The column is a foreign key linking to another table.

🚫 Avoid indexing if:

• The table is small (indexing overhead isn’t worth it).
• The column has many unique values (like id, which is already indexed as PRIMARY KEY).

What actually happens?

When you add an index to a column in Room, Room creates a separate data structure called a B-tree index. This makes queries that search for specific values in the indexed column much faster.

If you want to know more about B-tree Index: check this out B-Tree Index

Now we have learned about indexing lets checkout how to ensure the columns stays unique

3️⃣ Unique Constraints

Preventing duplicate values on an indexed column is sometimes necessary and we can achieve that by setting the property unique = true if the Index class, lets checkout an example to see how to apply this:

@Entity(
    tableName = "habit_tracker",
    indices = [
        Index(value = ["entry_data"], unique = true),
        Index(value = ["associated_habit_id"])
    ]
)
data class LocalHabitTracker(
    @PrimaryKey(autoGenerate = true) val id: Long,
    @ColumnInfo(name = "associated_habit_id")val associatedHabitId: Long,  
    val positionX: Int,
    val positionY: Int,
    val note: String,
    @ColumnInfo(name = "entry_data")val entryDate: String
)

• Ensures habit_id remains unique across all rows.

The unique = true ensures there is no duplicate value in that particular indexed row, this can be extremely helpful in some cases in our case we are building a habit tracking app where users log their habits daily. We want to ensure that a user cannot log the same habit more than once per day so this property help us to achieve that blissfully.

Lets move on to Keys and Relationships,i meant between the Entities 😜

4️⃣ Foreign Keys for Relationships (@ForeignKey)

Define relationships between tables using @ForeignKey.

@Entity(
    tableName = "habit_tracker",
    foreignKeys = [
        ForeignKey(
            entity = Habit::class,
            parentColumns = ["id"],
            childColumns = ["habit_id"],
            onDelete = ForeignKey.CASCADE
        )
    ]
)
data class LocalHabitTracker(
    @PrimaryKey(autoGenerate = true) val id: Long,
    val habit_id: Long,
    val positionX: Int,
    val positionY: Int,
    val note: String
)

🔷 habit_id references id from the Habit table. 🔷 onDelete = CASCADE ensures that deleting a Habit deletes all related LocalHabitTracker records.

The @ForeignKey is a primary key of an associated entity in the context of current entity the associated entity is referred as parent entity, using @ForeignKey help us to create relations and trigger changes depending on the event triggered, most commonly used trigger event is onDelete the other one is onUpdate the actions supported are as follows:

Supported Actions:

This table should have given you a clear picture of what each action’s behavior and next lets checkout how to select them and when to use them effectively:

When to Use Each Action

You can add any number of foreign keys so make use of it for simplifying and automate your preferred action when the parent entity is modified.

5️⃣ Embedded Objects (@Embedded)

Instead of creating separate tables, you can embed objects inside an entity, this does not mean that the table will hold your embedded object as is, it basically flattens the properties into the Entity, first lets see how to use @Embedded:

data class Position(
    val x: Int,
    val y: Int
)

@Entity
data class LocalHabitTracker(
    @PrimaryKey(autoGenerate = true) val id: Long,
    val associatedHabitId: Long,
    @Embedded val position: Position,
    val note: String
)

• The Position object is embedded as separate columns (x, y) in LocalHabitTracker,

This helps with structuring data efficiently without creating a separate table for nested objects, It is primarily used to flatten objects into separate columns within the same table this helps us to avoid using TypeConverters, extra Table, faster queries as we don’t have to deal with JOINS and other complications.

When to Use @Embedded:

1. You have small nested objects (e.g., Position, Address, Metadata).
2. You don’t need a separate table for the object.
3. You want to avoid TypeConverters for simple objects.
4. The embedded object is always used with the parent (it has no independent existence).

When to Avoid it:

1. The embedded object is large or frequently updated → Use a separate table.
2. The object has relationships with other entities → Use @Relation instead.
3. The object needs to be referenced from multiple entities → Use Foreign Keys.

I hope this made sense, simply put the @Embedded is only a output structure, while creating the SQL query room will flatten the properties into the entity table, Now if you want to store complex objects like lets say List event that is possible, lets see how to achieve it.

6️⃣ Storing Objects as is (TypeConverters)

Room only supports primitive data types (Int, Long, String, Boolean, etc.) by default. If you want to store complex data types (e.g., List, Date, Enum), you need Type Converters to convert them into a format Room understands ie String, lets look at an example of @TypeConverter:

import androidx.room.TypeConverter
import com.google.gson.Gson
import com.google.gson.reflect.TypeToken
import java.util.Date

class Converters {

    // Convert Date -> Long (for storage)
    @TypeConverter
    fun fromDate(date: Date?): Long? {
        return date?.time
    }

    // Convert Long -> Date (for retrieval)
    @TypeConverter
    fun toDate(timestamp: Long?): Date? {
        return timestamp?.let { Date(it) }
    }

    // Convert List<String> -> JSON String (for storage)
    @TypeConverter
    fun fromStringList(list: List<String>?): String {
        return Gson().toJson(list)
    }

    // Convert JSON String -> List<String> (for retrieval)
    @TypeConverter
    fun toStringList(json: String?): List<String> {
        return Gson().fromJson(json, object : TypeToken<List<String>>() {}.type)
    }
}

Once a converter is defined it must be added to the DataBase class,here is an example:

@Database(entities = [User::class], version = 1)
@TypeConverters(Converters::class)  // Register converters
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

now you can add it to the entity by annotating it with the the @TypeConverter, here is an example for it:

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

    @TypeConverters(Converters::class) // Apply TypeConverter here
    val hobbies: List<String>
)

The best use-case for this is when you want to store Enums, Dates and List of items, do note the values in the object will be stored but cannot be queried which means you can’t search, sort or filter the values so ensure you use them only when absolutely need to like for Storing simple objects (e.g., Address, Date, Enum)

These cover the most important aspects of the @Entity and its properties and how to use them effectively, if you think i have missed any please feel free to add comment and ill definitely add them here so it can be helpful for me and others, before you go lets check the best practices.

🔍 Best Practices

✅ Use autoGenerate = true for @PrimaryKey to avoid conflicts if you don’t have a server that provides it.
✅ Optimize query performance with @Index.
✅ Define @ForeignKey relationships to maintain integrity but optional for complex cases.
✅ Use @Ignore for transient fields that shouldn’t be stored in the database.
✅ Keep entity classes small and focused—avoid unnecessary logic inside them.
✅ Ensure Proper Indexing: Index frequently queried columns to improve performance.
✅ Use Primitive Types: Room doesn’t support custom objects directly. Use @TypeConverter if needed.

🚀 Conclusion

Room Entities form the foundation of Android’s database layer, allowing structured and efficient data management. By following best practices, you ensure scalable and maintainable database architectures.

Next we will explore Data Access Objects, Stay tuned for the next article in this series! 🚀

Final Thoughts

This is my journey in building an offline-first app. I’d love to hear your feedback, suggestions, or questions!

Feel free to connect with me on:
📩 Email
🌍 Website
💫 LinkedIn-Post for comments and feedbacks

🔖 Previous Article in this Series 🚀 Stay tuned for Part 5! 🚀

🔖 Next Article in this Series

On the previous article we have set-up the Room dependencies and plugins, Now lets get into the primary key components of a room library.

There are three important components: Entity, DAO’s, and Database.

• Entity represents a single row of a table. (Table structure)
• DAO’s (Data Access Objects) are interfaces to write queries and define operations.
• Database is where you associate entities and include the DAO’s you’d like to access from outside.

Let’s check it out one by one! 🔍

🏗️ Entities: Defining Your Data Structure

Any class annotated with @Entity is called a entity, it represents a table in a database, while designing the entity ensure you follow Normalizations Rules to keep it simple and future proof. Let’s look checkout a sample entity in a Habit Tracker app.

Example:

@Entity
data class LocalHabitTracker(
    @PrimaryKey(autoGenerate = true) val id: Long,
    val associatedHabitId: Long,
    val positionX: Int,
    val positionY: Int,
    val note: String
)

Key Points:

✅ An entity must have at least one parameter annotated with @PrimaryKey.
✅ The primary key must be unique the primaryKey column can’t have a duplicate key.
✅ If you want Room to auto-generate the primary key, set autoGenerate = true otherwise to false.
✅ Stick to primitive types like Long or Int as PrimaryKey.

The entity can be further customized with table names, indexing, custom column names, keys and more, which we’ll cover in next article. 🎯

🔗 DAOs: Your Data Gateway

DAOs or Data Access Objects serve as the interface between your app and the database, providing an abstraction layer. This is a bridge between you the developer and the Database all your interactions you intend to have table must be defined here later at compile time the compiler will generate the concrete classes for these at compile time, lets see an example how to define these interactions.

✍️ Example:

@Dao
interface HabitTrackerDao {

    // Query to get all habit trackers
    @Query("SELECT * FROM LocalHabitTracker")
    suspend fun getAll(): List<LocalHabitTracker>

    // Query to get a habit tracker by ID
    @Query("SELECT * FROM LocalHabitTracker WHERE id = :id")
    suspend fun getById(id: Long): LocalHabitTracker

    // Insert a new row into the table (fails if duplicate)
    @Insert
    suspend fun insert(habitTracker: LocalHabitTracker)

    // Update an existing row
    @Update
    suspend fun update(habitTracker: LocalHabitTracker)

    // Upsert: If exists, update; otherwise, insert
    @Upsert
    suspend fun upsert(habitTracker: LocalHabitTracker)

    // Delete a row from the table
    @Delete
    suspend fun delete(habitTracker: LocalHabitTracker)
}

Best Practices:

✅ One entity per DAO: It’s best to separate interaction with each table into its own DAO for maintainability.
✅ Keep queries optimized to avoid performance issues as your app scales.
✅ Inheritance if some of the interactions are common to other Dao’s create a new Dao with Common as prefix for exampleCommonHabitTrackerDao.

We’ll cover complex cases like @RawQuery, Junctions, and TableViews in later articles as to not over-complicate this! 🔮

🏛️ Database: The Central Hub

Now that we have defined the entities and DAOs, we need to create a database to integrate thee entity and Dao’s into its domain. Now the room can effectively generate its contents when instantiated along with this the database also manages the integrity validation, migrations and works as a central hub of control for our interactions with this database and its entities.

Here is an example of a database class:

@Database(
    entities = [LocalHabitTracker::class], // Add all your entities here
    version = 1 // Update this when modifying the schema
)
abstract class HabitTrackerDataBase : RoomDatabase() {

    // Room will auto-implement this function and return the DAO implementation
    abstract fun habitTrackerDao(): HabitTrackerDao

}

Important Notes:

✅ Always increase the version when modifying entities, it enables room to validate the integrity of tables and run migrations effectively.
✅ Room doesn’t know how to handle schema changes unless you define a migration strategy.
✅ Multiple databases can exist in an app, so this class serves as an entry point of the particular database.

Migrations and schema updates are crucial for real-world apps to prevent data loss. We’ll cover on later articles. 🔄

🎛️ Manually Creating and Using the Database

Now, let’s see how to manually create and interact with the database in our app.

✍️ Example:

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Creating the database manually
        val habitTrackerDB = Room.databaseBuilder(
            context = this, // ApplicationContext
            klass = HabitTrackerDataBase::class.java, // Database abstract class
            name = "habbit_tracker" // Custom database name
        ).build() 
        
        // Get the DAO implementation
        val habitTrackerDao = habitTrackerDB.habitTrackerDao()

        setContent {
            AppTheme {
                AppNav(activity = this, habitLocalService = habitTrackerDao)
            }
        }
    }
}

⚡ Pro Tips:

✅ Don’t use the UI thread for database operations; always use coroutines or background threads.
✅ In real-world apps, use Dependency Injection (DI) for managing database instances efficiently.
✅ Avoid creating multiple database instances, as it can lead to memory leaks and performance issues.

Mostly this is enough for creating simple CRUD apps, though it looks simple the entities will be converted into a query to create tables, A concrete classes will be created for each Dao’s and other essential tasks will be carried by room it self easing our development and debug process.

🚀 What’s Next?

This was a quick run through of some of the key components of room, on the next article we will dive a little deeper into @Entity its keys and customizations,as we have a larger purpose to explore them each in detail.

Final Thoughts

This is my journey in building an offline-first app. I’d love to hear your feedback, suggestions, or questions!

Feel free to connect with me on:
📩 Email
🌍 Website 💫 LinkedIn-Post for comments and feedbacks

🔖 Previous Article in this Series

🔖 Next Article in this Series

✅ Compile-time SQL Validation – Catches errors early by verifying SQL queries at compile time.
✅ Kotlin-first Approach – Supports coroutines, Flow, and LiveData natively.
✅ Less Boilerplate Code – Simplifies database interactions while maintaining SQLite’s power.
✅ Seamless Migration Handling – Built-in support for database migrations.

For a more detailed explanation, refer to the official Android documentation.

Official Documentation

Google keeps its documentation up to date with a simple setup guide. However, you might wonder why we need this article if the documentation is available.

Google’s documentation caters to both Java and Kotlin developers, but since most of us have migrated to Kotlin, we don’t need Java-specific instructions. This article focuses on a Kotlin-first approach to setting up Room.

📖 Official Guide on Setting up Room Dependencies and Plugins.

Setting up Dependencies

1️⃣ Configure Project-Level build.gradle.kts

Ensure your project-level build.gradle.kts file includes Google’s Maven repository and Maven Central, as these are where Room dependencies are hosted.

buildscript {
    repositories {
        google()
        mavenCentral()
    }
}

2️⃣ Add Room Dependencies

Head to your module-level build.gradle.kts file and add only the required Room dependencies inside the dependencies block:

dependencies {
    // Other dependencies 

    // Room Dependencies
    val room_version = "2.6.1"

    // Room Database Core
    implementation("androidx.room:room-runtime:$room_version")

    // Annotation Processor (KSP)
    ksp("androidx.room:room-compiler:$room_version")

    // Kotlin Extensions and Coroutines support for Room (Optional)
    implementation("androidx.room:room-ktx:$room_version")

}

🔎 Check for Latest Versions Always use the latest stable version of Room and KSP:

📌 Maven Central - Room Runtime 📌 kotlin-ksp-releases

3️⃣ Add the Room Plugin

Project-Level build.gradle.kts Add the Room plugin reference to the project-level build.gradle.kts file:

plugins {
    id("androidx.room") version "$room_version" apply false 
    id("com.google.devtools.ksp") version "2.0.21-1.0.27" apply false 
    // Other plugins...
}

Module-Level build.gradle.kts Add this to the module-level build.gradle file:

plugins {
    id("androidx.room")
    id("com.google.devtools.ksp")
}

4️⃣ Configure Schema Directory

Room allows schema export for better version control and database migrations. Let’s specify a schema directory inside the android {} block:

android {
    ...
    room {
        schemaDirectory("$projectDir/schemas")
    }
}

Sync & Verify Installation

Once you’ve added the dependencies and plugin, sync your Gradle project. If everything is set up correctly, you should have Room ready for use in our project! 🎉

./gradlew build 

Sample Code for a quick reference

I hope you had no issues setting up the dependencies, if you need a sample app to compare the change-set feel free to checkout this commit.

What’s Next?

This short article we have learned how to set-up the room dependencies to our projects and hopefully this was helpful: 📌 In the next part of this series, we’ll dive into:

1️⃣ Key Components of Room

• @Entity: Defines how data is stored in the table.
• @Dao: Specifies how to interact with the table (CRUD operations).
• @Database: Configures the database and associates Entities and DAOs.

2️⃣ How to create, access and interact with a simple database.

Final Thoughts

This is my journey in building an offline-first app. I’d love to hear your feedback, suggestions, or questions!

Feel free to connect with me on:
📩 Email
🌍 Website
💫 LinkedIn-Post for comments and feedbacks

🔖 Previous Article in this Series

🔖 Next Article in this Series

Making your app offline-first is essential if you want to provide the best user experience. It makes your app significantly faster by reducing the number of network calls, which in turn also reduces server costs.

What does Offline-First mean?

The core idea is to persist/store remote-fetched data on the device. This allows users to access the data instantly, skipping unnecessary network requests—until the data expires or is invalidated.

If your app has this feature then your app is offline-first if it does not then lets make it one.

While offline-first apps come with some complexities, the benefits far outweigh the challenges. but before we start a small disclaimer.

A Quick Disclaimer

There are multiple ways to approach offline-first implementation. What I discuss here is my approach, tailored to my requirements. There might be better methods for different scenarios so take these as suggestions and not rules.

If you have suggestions, feedback, or alternative approaches, I’d love to discuss them! Let’s learn and refine this together. As I explore further, I will actively update these articles with new insights/approaches/strategies.

Now, let’s get started. 🚀

Offline Strategies: Partial vs. Full Offline Mode

There are two main strategies for implementing offline-first functionality:

1. Fully Offline Mode
2. Partial Offline Mode

The main difference between them is whether the user can modify their data offline.

1️⃣ Fully Offline Mode (CRUD Operations Offline)

In this approach, users can:
✅ Create, Read, Update, and Delete (CRUD) without an internet connection.
✅ Sync data to the cloud when online.

🔴 Major Challenge:

• If a user forgets to sync data from one device (e.g., a tablet) and later accesses their account from another device (e.g., a phone), they might think the data is lost.
• This can frustrate users, leading to complaints or abandoning our app.

🔵 Idea Use case:

Best option for apps that does not support multi user and has single device login, but ⚠️ The data loss % is still significantly high if user forgets to connect online after the initial login and loses his device etc, but thats a tradeoff you have to live with.

While this approach offers true offline functionality, it introduces complex synchronization issues, making it harder to maintain data consistency across devices.

2️⃣ Partial Offline Mode (Read-Only When Offline)

In this approach, users can:
✅ View/Read data offline.
❌ Modify data (Create, Update, Delete) only when online.

🔹 Why We Chose This Approach:

• Multi-device users won’t face sync issues since data is always available in cloud.
• Less complexity & better error handling & almost no possibility of data loss.
• Data remains clean and consistent with the server.

🔵 Idea Use case:

Best option for most use-cases simple or complex or extremely complex data set apps, with or without multi-user or multiple-device-logins and what not.

This is most preferred due to its data-consistency point and much simpler to implement, Now checkout the next one.

3️⃣ Hybrid Offline Mode (Partially-restricted Write operations)

The Hybrid mode is using both discussed strategies depending on the use cases, for example you may allow the user to update their profile details or personal notes etc but not the public contents that can cause issue with other uses on the same org/team.

✅ View/Read data offline.
✅ Modify some data even if offline.
❌ Modify most data only if online.

🔵 Idea Use case:

Best option for most simple or complex apps, with or without multi-user but strictly allow only single-device-login, this enables the user to do write-operations to user specific data while restricting the same for other parts of the app, there are tradeoffs here as well but only a particular user will be affected in the org/team.

For me the partial offline mode stands out as best option and would suggest the same for most use-cases, we will be sticking with this through out this journey.

Now, let’s dive into how we fetch and synchronize data.

Data Synchronization Strategies

Once we are decided on partial offline mode, the next question is:
👉 How do we fetch data from the server and keep it updated?

There are two main synchronization approaches:

1️⃣ On-Demand (Pull-Based Synchronization)

• Data is fetched only when the user requests it.
• Data is invalidated when it expires or is manually deleted.
• Lightweight & user-centric—fetches only relevant data.

2️⃣ Clone (Push-Based Synchronization)

• The local database mirrors the entire remote database.
• Auto-updates when the server sends a flag indicating it was modified.
• Heavy & resource-intensive, as it may download unnecessary data.

🔹 Which One Did We Pick?
We chose On-Demand Synchronization since it’s:
✅ Efficient (fetches only what’s needed).
✅ Faster & lightweight (minimizes unnecessary data transfers).

However, we use mox of both lets call it a hybrid approach, we loaded some data that user will need on the navigating screen to ensure a better user experience. After that, everything is strictly on-demand the data is synced only based on user.

Which Local Database Library Should You Choose?

There are several local database solutions available, but we chose Google’s Room Persistence Library. Here’s why:

✅ Built on SQLite – but with a modern, developer-friendly API.
✅ Works seamlessly with Kotlin (supports data classes).
✅ Compile-time SQL query verification (reduces errors).
✅ Built-in support for LiveData, Flow, and Paging.
✅ Faster development (less boilerplate, easy migrations).

Using Room significantly accelerates development while maintaining a structured and reliable database. It’s my go-to solution, and I highly recommend it for Android and Kotlin Multiplatform (KMP) projects.

What’s Next?

This article laid the foundation for an offline-first architecture and explained why we chose partial offline mode & on-demand synchronization.

📌 In the next part of this series, we’ll dive into:

• Setting up Room in an Android.
• Exploring Key Components of Room.

Final Thoughts

This is my journey in building an offline-first app. I’d love to hear your feedback, suggestions, or questions!

Feel free to connect with me on:
📩 Email
🌍 Website
💫 LinkedIn-Post for comments and feedbacks

🔖 Next Article in this Series