@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

package/pipeline/skills/shared/external/room-database/references/patterns.md

@@ -0,0 +1,614 @@
+# Room Database Patterns
+
+Full code examples backing the guidance in `SKILL.md`. Headings mirror the
+SKILL.md sections.
+
+## Contents
+
+- [Entity Definition](#entity-definition)
+- [DAO Interface](#dao-interface)
+- [Database Setup](#database-setup)
+- [Reactive Queries with Flow](#reactive-queries-with-flow)
+- [TypeConverters](#typeconverters)
+- [Relations](#relations)
+- [Migration Strategies](#migration-strategies)
+- [Hilt Integration](#hilt-integration)
+- [Testing with In-Memory Database](#testing-with-in-memory-database)
+- [Encrypted Database (SQLCipher)](#encrypted-database-sqlcipher)
+- [Async Database Provisioning](#async-database-provisioning)
+- [Runtime Hygiene](#runtime-hygiene)
+
+## Entity Definition
+
+```kotlin
+@Entity(
+    tableName = "flights",
+    indices = [
+        Index(value = ["origin_code", "destination_code"]),
+        Index(value = ["departure_time"]),
+    ],
+)
+data class FlightEntity(
+    @PrimaryKey
+    val id: String,
+    @ColumnInfo(name = "origin_code")
+    val originCode: String,
+    @ColumnInfo(name = "origin_name")
+    val originName: String,
+    @ColumnInfo(name = "destination_code")
+    val destinationCode: String,
+    @ColumnInfo(name = "destination_name")
+    val destinationName: String,
+    @ColumnInfo(name = "departure_time")
+    val departureTime: String,
+    @ColumnInfo(name = "arrival_time")
+    val arrivalTime: String,
+    @ColumnInfo(name = "price_amount")
+    val priceAmount: Double,
+    @ColumnInfo(name = "price_currency")
+    val priceCurrency: String,
+    val status: String,
+    @ColumnInfo(name = "updated_at", defaultValue = "0")
+    val updatedAt: Long = System.currentTimeMillis(),
+)
+```
+
+### Composite Primary Key
+
+```kotlin
+@Entity(
+    tableName = "booking_passengers",
+    primaryKeys = ["booking_id", "passenger_id"],
+)
+data class BookingPassengerEntity(
+    @ColumnInfo(name = "booking_id")
+    val bookingId: String,
+    @ColumnInfo(name = "passenger_id")
+    val passengerId: String,
+    @ColumnInfo(name = "seat_number")
+    val seatNumber: String?,
+)
+```
+
+## DAO Interface
+
+```kotlin
+@Dao
+interface FlightDao {
+
+    @Query("SELECT * FROM flights WHERE origin_code = :origin AND destination_code = :destination ORDER BY departure_time ASC")
+    fun getFlights(origin: String, destination: String): Flow<List<FlightEntity>>
+
+    @Query("SELECT * FROM flights WHERE id = :id")
+    fun getFlightById(id: String): Flow<FlightEntity?>
+
+    @Query("SELECT * FROM flights WHERE id = :id")
+    suspend fun getFlightByIdOnce(id: String): FlightEntity?
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertFlight(flight: FlightEntity)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertFlights(flights: List<FlightEntity>)
+
+    @Upsert
+    suspend fun upsertFlights(flights: List<FlightEntity>)
+
+    @Update
+    suspend fun updateFlight(flight: FlightEntity)
+
+    @Delete
+    suspend fun deleteFlight(flight: FlightEntity)
+
+    @Query("DELETE FROM flights WHERE id = :id")
+    suspend fun deleteFlightById(id: String)
+
+    @Query("DELETE FROM flights WHERE updated_at < :threshold")
+    suspend fun deleteStaleFlights(threshold: Long)
+
+    @Query("SELECT COUNT(*) FROM flights")
+    fun getFlightCount(): Flow<Int>
+
+    @Transaction
+    suspend fun replaceAllFlights(flights: List<FlightEntity>) {
+        deleteAllFlights()
+        insertFlights(flights)
+    }
+
+    @Query("DELETE FROM flights")
+    suspend fun deleteAllFlights()
+}
+```
+
+### @Upsert vs @Insert(onConflict = REPLACE)
+
+| Strategy | Behavior | Use When |
+|----------|----------|----------|
+| `@Upsert` | Insert if absent, update if present (by PK) | Syncing remote data; preserves non-conflicting columns |
+| `@Insert(REPLACE)` | Delete + re-insert on conflict | Simpler; triggers delete cascade |
+| `@Insert(IGNORE)` | Skip on conflict | Inserting if not exists, no update needed |
+
+## Database Setup
+
+```kotlin
+@Database(
+    entities = [
+        FlightEntity::class,
+        BookingEntity::class,
+        BookingPassengerEntity::class,
+    ],
+    version = 2,
+    autoMigrations = [
+        AutoMigration(from = 1, to = 2),
+    ],
+    exportSchema = true,
+)
+@TypeConverters(Converters::class)
+abstract class AppDatabase : RoomDatabase() {
+    abstract fun flightDao(): FlightDao
+    abstract fun bookingDao(): BookingDao
+}
+```
+
+Always set `exportSchema = true` and configure the schema export directory in
+`build.gradle.kts`:
+
+```kotlin
+ksp {
+    arg("room.schemaLocation", "$projectDir/schemas")
+}
+```
+
+## Reactive Queries with Flow
+
+DAO methods returning `Flow` automatically emit new values when the underlying
+table changes.
+
+```kotlin
+// DAO returns Flow
+@Query("SELECT * FROM flights WHERE origin_code = :origin")
+fun getFlightsByOrigin(origin: String): Flow<List<FlightEntity>>
+
+// Repository maps to domain models
+class FlightRepositoryImpl @Inject constructor(
+    private val dao: FlightDao,
+    private val mapper: FlightMapper,
+) : FlightRepository {
+
+    override fun getFlights(origin: String): Flow<List<Flight>> =
+        dao.getFlightsByOrigin(origin)
+            .map { entities -> entities.map(mapper::toDomain) }
+            .flowOn(Dispatchers.IO)
+}
+
+// ViewModel collects in viewModelScope
+@HiltViewModel
+class FlightListViewModel @Inject constructor(
+    private val repository: FlightRepository,
+) : ViewModel() {
+
+    val flights: StateFlow<List<Flight>> = repository.getFlights("IST")
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = emptyList(),
+        )
+}
+
+// Compose collects as state
+@Composable
+fun FlightListScreen(viewModel: FlightListViewModel = hiltViewModel()) {
+    val flights by viewModel.flights.collectAsStateWithLifecycle()
+    LazyColumn {
+        items(flights, key = { it.id }) { flight ->
+            FlightCard(flight = flight)
+        }
+    }
+}
+```
+
+## TypeConverters
+
+For types Room does not natively support (lists, enums, dates).
+
+```kotlin
+class Converters {
+
+    private val json = Json { ignoreUnknownKeys = true }
+
+    @TypeConverter
+    fun fromStringList(value: List<String>): String =
+        json.encodeToString(value)
+
+    @TypeConverter
+    fun toStringList(value: String): List<String> =
+        json.decodeFromString(value)
+
+    @TypeConverter
+    fun fromInstant(value: Instant?): Long? = value?.toEpochMilliseconds()
+
+    @TypeConverter
+    fun toInstant(value: Long?): Instant? = value?.let { Instant.fromEpochMilliseconds(it) }
+
+    @TypeConverter
+    fun fromFlightStatus(value: FlightStatus): String = value.name
+
+    @TypeConverter
+    fun toFlightStatus(value: String): FlightStatus = FlightStatus.valueOf(value)
+}
+```
+
+Register in `@Database`:
+
+```kotlin
+@Database(entities = [...], version = 1)
+@TypeConverters(Converters::class)
+abstract class AppDatabase : RoomDatabase()
+```
+
+## Relations
+
+### @Embedded
+
+Flatten a nested object into the parent table columns:
+
+```kotlin
+data class AddressEntity(
+    val street: String,
+    val city: String,
+    val country: String,
+)
+
+@Entity(tableName = "passengers")
+data class PassengerEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    @Embedded(prefix = "address_")
+    val address: AddressEntity,
+)
+// Creates columns: id, name, address_street, address_city, address_country
+```
+
+### @Relation (One-to-Many)
+
+```kotlin
+data class BookingWithPassengers(
+    @Embedded val booking: BookingEntity,
+    @Relation(
+        parentColumn = "id",
+        entityColumn = "booking_id",
+    )
+    val passengers: List<BookingPassengerEntity>,
+)
+
+@Dao
+interface BookingDao {
+    @Transaction
+    @Query("SELECT * FROM bookings WHERE id = :bookingId")
+    fun getBookingWithPassengers(bookingId: String): Flow<BookingWithPassengers?>
+}
+```
+
+### Junction Table (Many-to-Many)
+
+```kotlin
+@Entity(
+    tableName = "flight_tags",
+    primaryKeys = ["flight_id", "tag_id"],
+)
+data class FlightTagCrossRef(
+    @ColumnInfo(name = "flight_id") val flightId: String,
+    @ColumnInfo(name = "tag_id") val tagId: String,
+)
+
+data class FlightWithTags(
+    @Embedded val flight: FlightEntity,
+    @Relation(
+        parentColumn = "id",
+        entityColumn = "id",
+        associateBy = Junction(
+            value = FlightTagCrossRef::class,
+            parentColumn = "flight_id",
+            entityColumn = "tag_id",
+        ),
+    )
+    val tags: List<TagEntity>,
+)
+```
+
+Always annotate relation queries with `@Transaction` to ensure consistent reads.
+
+## Migration Strategies
+
+### Auto Migration (Room 2.4+)
+
+For simple schema changes (add column, add table, add index):
+
+```kotlin
+@Database(
+    entities = [FlightEntity::class],
+    version = 3,
+    autoMigrations = [
+        AutoMigration(from = 1, to = 2),
+        AutoMigration(from = 2, to = 3, spec = Migration2To3::class),
+    ],
+)
+abstract class AppDatabase : RoomDatabase()
+
+// Spec needed for column/table renames or deletes
+@RenameColumn(tableName = "flights", fromColumnName = "price", toColumnName = "price_amount")
+class Migration2To3 : AutoMigrationSpec
+```
+
+### Manual Migration
+
+For complex changes (data transformation, merging tables):
+
+```kotlin
+val MIGRATION_3_4 = object : Migration(3, 4) {
+    override fun migrate(db: SupportSQLiteDatabase) {
+        db.execSQL("""
+            CREATE TABLE IF NOT EXISTS bookings_new (
+                id TEXT NOT NULL PRIMARY KEY,
+                flight_id TEXT NOT NULL,
+                status TEXT NOT NULL DEFAULT 'PENDING',
+                created_at INTEGER NOT NULL DEFAULT 0,
+                FOREIGN KEY (flight_id) REFERENCES flights(id) ON DELETE CASCADE
+            )
+        """)
+        db.execSQL("""
+            INSERT INTO bookings_new (id, flight_id, status, created_at)
+            SELECT id, flight_id, status, 0 FROM bookings
+        """)
+        db.execSQL("DROP TABLE bookings")
+        db.execSQL("ALTER TABLE bookings_new RENAME TO bookings")
+    }
+}
+
+// Register in Hilt module
+Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
+    .addMigrations(MIGRATION_3_4)
+    .build()
+```
+
+### Fallback to Destructive Migration
+
+Only for development or non-critical data:
+
+```kotlin
+Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
+    .fallbackToDestructiveMigration()
+    .build()
+```
+
+## Hilt Integration
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+object DatabaseModule {
+
+    @Provides
+    @Singleton
+    fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
+        Room.databaseBuilder(
+            context,
+            AppDatabase::class.java,
+            "app.db",
+        )
+        .addMigrations(MIGRATION_3_4)
+        .build()
+
+    @Provides
+    fun provideFlightDao(database: AppDatabase): FlightDao =
+        database.flightDao()
+
+    @Provides
+    fun provideBookingDao(database: AppDatabase): BookingDao =
+        database.bookingDao()
+}
+```
+
+## Testing with In-Memory Database
+
+```kotlin
+class FlightDaoTest {
+
+    private lateinit var database: AppDatabase
+    private lateinit var dao: FlightDao
+
+    @Before
+    fun setup() {
+        database = Room.inMemoryDatabaseBuilder(
+            ApplicationProvider.getApplicationContext(),
+            AppDatabase::class.java,
+        )
+        .allowMainThreadQueries() // OK for tests only
+        .build()
+
+        dao = database.flightDao()
+    }
+
+    @After
+    fun tearDown() {
+        database.close()
+    }
+
+    @Test
+    fun insertAndQuery_returnsCorrectFlight() = runTest {
+        val flight = FlightEntity(
+            id = "TK1",
+            originCode = "IST",
+            originName = "Istanbul",
+            destinationCode = "JFK",
+            destinationName = "New York",
+            departureTime = "2025-01-15T10:00:00Z",
+            arrivalTime = "2025-01-15T18:00:00Z",
+            priceAmount = 799.0,
+            priceCurrency = "USD",
+            status = "SCHEDULED",
+        )
+
+        dao.insertFlight(flight)
+
+        val result = dao.getFlightByIdOnce("TK1")
+        assertThat(result).isNotNull()
+        assertThat(result?.originCode).isEqualTo("IST")
+    }
+
+    @Test
+    fun flowQuery_emitsUpdates() = runTest {
+        dao.getFlights("IST", "JFK").test {
+            assertThat(awaitItem()).isEmpty()
+
+            dao.insertFlight(testFlight)
+
+            val updated = awaitItem()
+            assertThat(updated).hasSize(1)
+
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+
+    @Test
+    fun upsert_updatesExistingFlight() = runTest {
+        dao.insertFlight(testFlight)
+        val updated = testFlight.copy(status = "DELAYED")
+        dao.upsertFlights(listOf(updated))
+
+        val result = dao.getFlightByIdOnce(testFlight.id)
+        assertThat(result?.status).isEqualTo("DELAYED")
+    }
+}
+```
+
+### Testing Migrations
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class MigrationTest {
+
+    @get:Rule
+    val helper = MigrationTestHelper(
+        InstrumentationRegistry.getInstrumentation(),
+        AppDatabase::class.java,
+    )
+
+    @Test
+    fun migrate3To4() {
+        // Create database at version 3
+        helper.createDatabase("test-db", 3).apply {
+            execSQL("INSERT INTO bookings (id, flight_id, status) VALUES ('B1', 'F1', 'CONFIRMED')")
+            close()
+        }
+
+        // Run migration and validate
+        val db = helper.runMigrationsAndValidate("test-db", 4, true, MIGRATION_3_4)
+        val cursor = db.query("SELECT * FROM bookings WHERE id = 'B1'")
+        assertThat(cursor.moveToFirst()).isTrue()
+        assertThat(cursor.getColumnIndex("created_at")).isAtLeast(0)
+    }
+}
+```
+
+## Encrypted Database (SQLCipher)
+
+Encrypt the database file by passing a SQLCipher `SupportOpenHelperFactory` to
+`.openHelperFactory(...)`. This skill owns only the Room wiring. The passphrase
+must come from a hardware-backed key hierarchy; the derivation and storage of
+that key are the `android-security` skill's responsibility, not reproduced here.
+
+```kotlin
+fun buildEncryptedDatabase(
+    context: Context,
+    passphrase: ByteArray,
+): AppDatabase {
+    val factory = SupportOpenHelperFactory(passphrase)
+    return Room.databaseBuilder(context, AppDatabase::class.java, "secure-app.db")
+        .openHelperFactory(factory)
+        .addCallback(WalHygieneCallback())
+        .build()
+}
+```
+
+`SupportOpenHelperFactory` is from the AndroidX-compatible SQLCipher artifact
+(`net.zetetic.database.sqlcipher`); it zeroes the passphrase array after use.
+
+## Async Database Provisioning
+
+When the passphrase must be derived or fetched before `Room.databaseBuilder`, a
+synchronous `@Provides` cannot express the await. Expose the database through a
+suspend, `Mutex`-guarded, double-checked lazy singleton provider.
+
+```kotlin
+@Singleton
+class DatabaseProvider @Inject constructor(
+    @ApplicationContext private val context: Context,
+    private val keyProvider: DatabaseKeyProvider,
+) {
+    private val mutex = Mutex()
+    @Volatile private var instance: AppDatabase? = null
+
+    suspend fun database(): AppDatabase {
+        instance?.let { return it }
+        return mutex.withLock {
+            instance ?: buildDatabase().also { instance = it }
+        }
+    }
+
+    private suspend fun buildDatabase(): AppDatabase {
+        val passphrase = keyProvider.passphrase()
+        return Room.databaseBuilder(context, AppDatabase::class.java, "secure-app.db")
+            .openHelperFactory(SupportOpenHelperFactory(passphrase))
+            .addCallback(WalHygieneCallback())
+            .build()
+    }
+}
+```
+
+The Hilt module provides `DatabaseProvider` (no I/O); repositories obtain DAOs
+from a suspend accessor (`provider.database().recentSearchDao()`) at call time.
+
+## Runtime Hygiene
+
+Cap WAL growth on a write-heavy database with an `onOpen` PRAGMA:
+
+```kotlin
+class WalHygieneCallback : RoomDatabase.Callback() {
+    override fun onOpen(db: SupportSQLiteDatabase) {
+        db.query("PRAGMA wal_autocheckpoint=1000").close()
+    }
+}
+```
+
+Do multi-step read-then-write logic atomically in a `@Transaction` DAO default
+method -- dedupe, insert, and trim-to-cap in one transaction:
+
+```kotlin
+@Dao
+interface RecentSearchDao {
+    @Query("SELECT id FROM recent_searches WHERE query = :query LIMIT 1")
+    suspend fun findId(query: String): Long?
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insert(entity: RecentSearchEntity): Long
+
+    @Query(
+        "DELETE FROM recent_searches WHERE id IN " +
+            "(SELECT id FROM recent_searches ORDER BY updated_at DESC LIMIT -1 OFFSET :cap)",
+    )
+    suspend fun trimToCap(cap: Int)
+
+    @Transaction
+    suspend fun record(entity: RecentSearchEntity, cap: Int) {
+        val existing = findId(entity.query)
+        insert(if (existing != null) entity.copy(id = existing) else entity)
+        trimToCap(cap)
+    }
+}
+```
+
+`exportSchema = false` is acceptable only for a cache or destructive-fallback
+database, where the file is disposable. A migration-tested production database
+must keep `exportSchema = true` and commit the schema JSON, since
+`MigrationTestHelper` validates against the exported schema.