Name: Write Local Datasource
Author: igorescodro

Overview

The local data layer spans eight phases per entity: DataSource interface, SQLDelight schema, DB migrations, DAO interface, DAO implementation, local mapper, LocalDataSource implementation, and DI registration. All phases must follow strict conventions.

Phases

DataSource Interface — Contract the RepositoryImpl depends on; uses repository models (not local types) → see references/DATASOURCE_INTERFACE.md
SQLDelight Schema — .sq schema file with named queries and field prefixes → see references/SCHEMA.md
DB Migrations — .sqm file required for any structural change to an existing table → see references/MIGRATIONS.md
DAO Interface — Observable streams vs. single reads contract → see references/DAO.md
DAO Implementation — asFlow().mapToList() and executeAsOneOrNull() patterns → see references/DAO.md
— SQLDelight type ↔ repository model (/) → see

Overview

Phases

DataSource Interface — Contract the RepositoryImpl depends on; uses repository models (not local types) → see references/DATASOURCE_INTERFACE.md
SQLDelight Schema — .sq schema file with named queries and field prefixes → see references/SCHEMA.md
DB Migrations — .sqm file required for any structural change to an existing table → see references/MIGRATIONS.md
DAO Interface — Observable streams vs. single reads contract → see references/DAO.md
DAO Implementation — asFlow().mapToList() and executeAsOneOrNull() patterns → see references/DAO.md
— SQLDelight type ↔ repository model (/) → see

Rule	Details
Flow vs. suspend in DAO	`Flow<List<T>>` for reactive reads; `suspend` for mutations and point-in-time reads
No direct Queries access	LocalDataSource injects the DAO — never `*Queries` directly
executeAsOneOrNull	Always nullable for single reads — never `executeAsOne()`
cleanTable required	Every table needs a `cleanTable:` query for E2E test teardown
Field prefix	Column names prefixed with table name in snake_case (e.g., `category_id`)
DI scope	`singleOf` for DataSources and DAOs; `factoryOf` for mappers
Migration required	Any structural change to an existing table needs a `.sqm` file

Mistake	Fix
`suspend fun findAll()` for a Flow return	Use `fun findAll(): Flow<List<T>>` — no suspend for reactive reads
Calling `.first()` in DaoImpl for a Flow return	Return `Flow` directly; callers decide when to collect
Using `executeAsOne()` for single reads	Always `executeAsOneOrNull()` — assume nullable
Omitting `cleanTable:` in the `.sq` file	Required for E2E tests to reset state between runs
Local mapper in `data/repository/mapper/`	Belongs in `data/local/mapper/` with `toRepo`/`fromRepo`
Registering DataSource or DAO as `factoryOf`	Always `singleOf` — they share database state
Adding `DatabaseProvider` registration again	Already registered once; duplicate causes a Koin conflict
Accessing `*Queries` in LocalDataSource	Injects the DAO — never the queries object
Changing `CREATE TABLE` without a `.sqm` file	Existing users never see the change; always add a migration
Adding a `NOT NULL` column without `DEFAULT`	SQLite rejects the statement on existing rows
Editing an existing `.sqm` file	`.sqm` files are immutable; create a new file for each change
Wrong `.sqm` file number	Number must equal the count of existing `.sqm` files
Wrapping migration SQL in `BEGIN`/`END TRANSACTION`	The driver manages the transaction; wrapping can cause crashes

Write Local Datasource

Overview

Phases

Write Local Datasource

Overview

Phases

Rules

Common Mistakes

Testing

Verify

Database Migrations

Database Migrations

Postgres Patterns

Frontend Query & Mutation

Db Migrations

Drizzle