Room Database, Transactions, Relations, and Migrations

Published by Programming Line in Android App Development with Kotlin and Jetpack Compose. Last updated .

Module: Data and Offline Workflows · Lecture 20 of 33

Persist structured data with compile-time SQL checks, observable queries, transactions, and tested schema evolution. This lecture moves from the mental model to implementation, diagnosis, testing, and production tradeoffs.

Prerequisites and Learning Outcomes

Complete the previous lecture and retain its working project. By the end, you should be able to explain the responsibility, implement the example, force a realistic failure, and defend where the behavior belongs in the architecture.

  • Explain the concept without relying on framework buzzwords.
  • Implement it with idiomatic, null-safe Kotlin.
  • Verify success, empty, loading, cancellation, and failure states when applicable.
  • Write a focused automated test and identify one production risk.

Conceptual Model

1. Entities describe stored tables while domain models describe application meaning.

This principle changes an implementation decision, not only vocabulary. Identify the owner, input, output, lifetime, and failure behavior before adding framework code. Then isolate the rule behind a small typed boundary so it can be tested without launching the complete application.

To prove understanding, create one valid example and one counterexample. Predict the result, run the analyzer or test, and explain why the observed behavior follows from the Android or Kotlin model described above.

2. DAO suspend functions handle one-shot work and Flow queries observe changes.

This principle changes an implementation decision, not only vocabulary. Identify the owner, input, output, lifetime, and failure behavior before adding framework code. Then isolate the rule behind a small typed boundary so it can be tested without launching the complete application.

To prove understanding, create one valid example and one counterexample. Predict the result, run the analyzer or test, and explain why the observed behavior follows from the Android or Kotlin model described above.

3. Exported schemas and migration tests protect real user data across upgrades.

This principle changes an implementation decision, not only vocabulary. Identify the owner, input, output, lifetime, and failure behavior before adding framework code. Then isolate the rule behind a small typed boundary so it can be tested without launching the complete application.

To prove understanding, create one valid example and one counterexample. Predict the result, run the analyzer or test, and explain why the observed behavior follows from the Android or Kotlin model described above.

Mental-model exercise

Draw the runtime path for this feature as boxes and arrows. Include the user or operating-system event, composable, state owner, ViewModel when appropriate, repository, data source, and final rendered state. Mark which arrows are synchronous, suspending, streamed, or external to the process. Next, mark every place that can fail or be canceled. This diagram should make duplicate ownership, hidden dependencies, and missing recovery paths visible before the implementation becomes large.

Worked Kotlin Example

Type this example into the course project. Read the public contract first, trace one input through every line, and identify what owns any state or resource.

@Dao
interface TaskDao {
  @Query("SELECT * FROM tasks ORDER BY updatedAt DESC") fun observeAll(): Flow<List<TaskEntity>>
  @Upsert suspend fun upsert(tasks: List<TaskEntity>)
}

Walkthrough

  1. Locate the inputs and their nullability or validity constraints.
  2. Trace the successful path and write down the value and type of each important expression.
  3. Change one assumption: use absent, malformed, delayed, denied, very large, or stale data as appropriate.
  4. Check lifecycle and cancellation behavior by leaving and returning to the screen.
  5. Extract business or data policy from UI code and protect it with a unit test.

Guided Lab

Commit after each verified step. The commit history should tell the story of the feature and make failed experiments recoverable.

Step 1: Create an entity, DAO, and in-memory database test.

Implement this in a dedicated branch. Keep the change narrow, run the relevant Gradle task, and inspect the behavior on a representative emulator or device. Record the expected result before execution and retain a focused test or repeatable verification command.

Step 2: Write a transaction updating related records.

Implement this in a dedicated branch. Keep the change narrow, run the relevant Gradle task, and inspect the behavior on a representative emulator or device. Record the expected result before execution and retain a focused test or repeatable verification command.

Step 3: Add a column and test migration from the previous schema.

Implement this in a dedicated branch. Keep the change narrow, run the relevant Gradle task, and inspect the behavior on a representative emulator or device. Record the expected result before execution and retain a focused test or repeatable verification command.

Debugging Workshop

Advanced Android work depends on explaining failures across the OS, lifecycle, coroutine, data, and rendering boundaries. Practice with the following cases.

Failure 1

Using destructive migration in production by default.

Reproduce the symptom with fixed input. Reduce it to the smallest component or layer, inspect lifecycle and ownership, correct the underlying contract, and add a regression test. Avoid hiding the failure with a delay, null assertion, broad catch, or UI-only workaround.

Failure 2

Performing several dependent writes outside a transaction.

Reproduce the symptom with fixed input. Reduce it to the smallest component or layer, inspect lifecycle and ownership, correct the underlying contract, and add a regression test. Avoid hiding the failure with a delay, null assertion, broad catch, or UI-only workaround.

Architecture and Production Decisions

  • Ownership: state and resources need one clear owner and matching cleanup lifetime.
  • Dependency direction: composables render and emit events; ViewModels coordinate screen behavior; repositories own application data; data sources own transport or persistence details.
  • Reliability: distinguish retryable failures from authentication, validation, conflict, and permanent failures.
  • Accessibility: verify semantics, focus, touch target size, font scaling, contrast, and non-visual state feedback.
  • Performance: measure release-like behavior with traces or benchmarks before optimizing.
  • Security: validate external input, minimize stored data, authorize on the server, and keep privileged secrets out of the application.

Independent Assignment

Build: Create an entity, DAO, and in-memory database test. Write a transaction updating related records. Add a column and test migration from the previous schema.

Add a realistic failure and recovery path that the worked example does not already show. Submit source, analyzer and test output, one screenshot or trace where useful, and a short architecture note explaining ownership and tradeoffs.

Knowledge Check

  1. What problem does this concept solve?
  2. Which layer owns it, and which layer must not own it?
  3. What happens during configuration change, backgrounding, cancellation, or process death?
  4. Which malformed or adversarial input should be tested?
  5. What evidence would demonstrate production readiness?

Answer guide

A complete answer must use these facts: Entities describe stored tables while domain models describe application meaning. DAO suspend functions handle one-shot work and Flow queries observe changes. Exported schemas and migration tests protect real user data across upgrades.

It should name an observable behavior, a failure state, and a test boundary. Performance claims need measurement; security claims need a server-side trust boundary; accessibility claims need semantics and device-level verification.

Summary and Official Reference

Entities describe stored tables while domain models describe application meaning. DAO suspend functions handle one-shot work and Flow queries observe changes. Exported schemas and migration tests protect real user data across upgrades.

Compare your work with the official Android documentation for this topic. You are ready to continue when you can rebuild the central example, explain its lifecycle and ownership, and show a passing regression test.

Complete Android curriculum · Previous: Networking, Serialization, and Typed API Failures · Next: Preferences DataStore and Typed Settings