Pocket Notes 1 — model, Room and DAO

The most valuable zero in the course

Dice Duel forgets. Roll a twenty-game winning streak, swipe the app away, open it again — nothing. That was fine. A dice game is a moment, not a record.

Pocket Notes is the opposite. A notes app that loses your notes is not a worse notes app, it is not a notes app at all. Everything in the next six chapters hangs off one requirement: the words have to still be there tomorrow.

So this chapter builds the skeleton and the memory, and then finishes on a screen so plain it looks like a mistake. One line of text:

0 notes stored

That zero is worth more than any animation. It did not come from a variable you set to zero. It came from a real SQLite database that opened on the device, ran a real SELECT COUNT(*), and answered honestly. If you can get that zero, everything after it is detail.

Start the project

This is a new app, not a change to Dice Duel. The settings are the same shape as Dice Duel's, with a different name.

The one addition is a fourth Gradle plugin called KSP — Kotlin Symbol Processing. KSP is the tool that reads your annotated Kotlin at build time and writes new Kotlin next to it. Room is a KSP plugin. Without this line, Room's annotations are just decoration.

1plugins {
2    alias(libs.plugins.android.application)
3    alias(libs.plugins.kotlin.android)
4    alias(libs.plugins.kotlin.compose)
5    alias(libs.plugins.ksp)
6}

Then three Room dependencies at the bottom of the same file:

1    // Room: the runtime, the Kotlin/coroutine helpers,
2    // and the code generator that writes the SQL.
3    implementation(libs.androidx.room.runtime)
4    implementation(libs.androidx.room.ktx)
5    ksp(libs.androidx.room.compiler)
6}

Look at that third line. It is ksp(...), not implementation(...). That is not a style choice. implementation means ship this library inside my app. ksp means run this at build time to generate code. Room's compiler is only ever needed on the workbench, never on the phone, and getting this one word wrong produces a crash we will meet at the end of the lesson.

Those names come from the version catalog, which already knows about Room:

1[versions]
2room = "2.6.1"
3
4[libraries]
5androidx-room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
6androidx-room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
7androidx-room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }

The theme is a warm one — honey and paper rather than the usual blue. It follows the same Theme.kt / Type.kt / Shape.kt pattern you built for Dice Duel, so the wrapper will look familiar:

1@Composable
2fun PocketNotesTheme(
3    darkTheme: Boolean = isSystemInDarkTheme(),
4    content: @Composable () -> Unit
5) {
6    MaterialTheme(
7        colorScheme =
8            if (darkTheme) DarkColors else LightColors,
9        typography = PocketTypography,
10        shapes = PocketShapes,
11        content = content
12    )
13}

LightColors and DarkColors above it are long lists of Color(0xFF…) values — about forty lines each, and nothing new. They are in the checkpoint ZIP at the bottom of this lesson. The rest of the chapter is the part that matters.

The card: one class, one table

Here is the whole data model of Pocket Notes.

Every property has a default. That is what lets chapter 4 write Note(title = "Shopping") without spelling out the other three.

The requests: an interface you never implement

Now the person who fetches cards. In Room this is a DAO — a Data Access Object — and the surprising thing about it is that it is an interface with no body anywhere.

Why an interface, and not a class?

Because you are not describing how. You are describing what.

A class would mean writing the SQL, opening a cursor, reading each column by index, building a Note, closing the cursor, and doing it again for the next query. Hundreds of lines of code where every one of the mistakes is silent — a column read in the wrong order gives you a note whose title is a date.

An interface means Room can do that. And because Room does it at build time, your SQL is checked at build time too. Misspell a column and the compiler stops you, on your phone, in seconds. Compare that with the traditional alternative, where a typo in a query string is a crash your users find for you.

That is the whole trade: you give up writing the code, and you get an error message instead of a bug report.

Why every disk function is suspend

Reading from storage takes time. Not much — a millisecond or two — but it is time your app spends not drawing.

Android gives you one thread for drawing, called the main thread. Everything the user can see happens on it. Sixty frames a second means that thread has 16 milliseconds to do everything, and if it is waiting on a disk read it is not drawing, and the screen freezes.

So Room simply refuses. Call a blocking database function on the main thread and you get an exception with an unusually clear message:

Cannot access database on the main thread since it may potentially lock the UI for a long period of time.

Marking the DAO functions suspend makes that impossible to get wrong. A suspend function can only be called from a coroutine, a coroutine knows how to wait without blocking, and Room quietly moves the work to a background thread for you.

The box itself

One class, three annotations, and a lump of ceremony that guarantees the database is opened exactly once.

This pattern — one shared instance, created lazily, guarded by a lock — is called a singleton. Databases are the textbook case. Opening a second connection to the same file is slow at best, and at worst two connections disagree about what is in it.

Prove it opens

Now the boring screen, which is the whole point of the chapter.

1@Composable
2fun DatabaseCheckScreen() {
3    val context = LocalContext.current
4    val type = MaterialTheme.typography
5    val colors = MaterialTheme.colorScheme
6
7    var count by remember {
8        mutableStateOf<Int?>(null)
9    }
10
11    // Runs once, in a coroutine, when the screen appears.
12    LaunchedEffect(Unit) {
13        val dao = NotesDatabase.get(context).noteDao()
14        count = dao.count()
15    }

count is Int? — nullable — and starts at null. That is not an accident. null here means we have not asked yet, which is a genuinely different state from 0, meaning we asked and there are none. Squash the two together and your screen tells a small lie for the first frame.

LaunchedEffect is the bridge. It runs its block in a coroutine when the composable first appears, which is exactly the kind of place a suspend function is allowed to be called from. Unit as the key means "start once, never restart".

The rest is a centred Scaffold with two Texts, and one when that turns the nullable number into words:

1            Text(
2                text = when (val c = count) {
3                    null -> "Opening the database…"
4                    else -> "$c notes stored"
5                },
6                style = type.bodyLarge,
7                color = colors.onSurfaceVariant,
8                textAlign = TextAlign.Center
9            )

No app bar. No buttons. Nothing to tap. If your phone is in dark mode the page is #17110E and the text is #EDE0D4, because the theme carries both schemes and Android picks one.