OpenParable
Skip to content
← Back to skills

Write Local Datasource

Development
write-local-datasource

Write Local Datasource is an Agent Skill for development published in the igorescodro/alkaa repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when a new feature needs to persist data locally in Alkaa — triggers on tasks like "add database support", "create a new table", "store this data in SQLDelight", or when write-feature Phase 2 requires a new entity in the local database.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/igorescodro/alkaa/blob/HEAD/.claude/skills/write-local-datasource/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/write-local-datasource, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Write Local DataSource

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

  1. DataSource Interface — Contract the RepositoryImpl depends on; uses repository models (not local types) → see references/DATASOURCE_INTERFACE.md
  2. SQLDelight Schema — .sq schema file with named queries and field prefixes → see references/SCHEMA.md
  3. DB Migrations — .sqm file required for any structural change to an existing table → see references/MIGRATIONS.md
  4. DAO Interface — Observable streams vs. single reads contract → see references/DAO.md
  5. DAO Implementation — asFlow().mapToList() and executeAsOneOrNull() patterns → see references/DAO.md
  6. Local Mapper — SQLDelight type ↔ repository model (toRepo/fromRepo) → see references/MAPPER.md
  7. LocalDataSource Implementation — Injects DAO + mapper; never accesses *Queries directly → see references/LOCAL_DATASOURCE.md
  8. DI Registration — singleOf for DAOs/DataSources, factoryOf for mappers → see references/DI.md

Rules

RuleDetails
Flow vs. suspend in DAOFlow<List<T>> for reactive reads; suspend for mutations and point-in-time reads
No direct Queries accessLocalDataSource injects the DAO — never *Queries directly
executeAsOneOrNullAlways nullable for single reads — never executeAsOne()
cleanTable requiredEvery table needs a cleanTable: query for E2E test teardown
Field prefixColumn names prefixed with table name in snake_case (e.g., category_id)
DI scopesingleOf for DataSources and DAOs; factoryOf for mappers
Migration requiredAny structural change to an existing table needs a .sqm file

Common Mistakes

MistakeFix
suspend fun findAll() for a Flow returnUse fun findAll(): Flow<List<T>> — no suspend for reactive reads
Calling .first() in DaoImpl for a Flow returnReturn Flow directly; callers decide when to collect
Using executeAsOne() for single readsAlways executeAsOneOrNull() — assume nullable
Omitting cleanTable: in the .sq fileRequired 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 factoryOfAlways singleOf — they share database state
Adding DatabaseProvider registration againAlready registered once; duplicate causes a Koin conflict
Accessing *Queries in LocalDataSourceInjects the DAO — never the queries object
Changing CREATE TABLE without a .sqm fileExisting users never see the change; always add a migration
Adding a NOT NULL column without DEFAULTSQLite 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 numberNumber must equal the count of existing .sqm files
Wrapping migration SQL in BEGIN/END TRANSACTIONThe driver manages the transaction; wrapping can cause crashes

Testing

After completing the local data layer, use the write-unit-tests skill to test data sources and use cases. Use the write-e2e-tests skill for full-flow coverage — E2E tests use DAOs directly (by inject()) to seed and clean data.

Verify

.claude/skills/write-local-datasource/scripts/verify_migrations.sh