KMP Room Multiplatform SQLite Connection Pool and Dispatcher Boundary Guardrail

--- description: KMP Room Multiplatform SQLite Connection Pool and Dispatcher Boundary Guardrail - Enforces strict asynchronous dispatcher isolation and connection pool boundary configuration across Android and iOS/Darwin runtimes in Room Multiplatform. Prevents catastrophic SQLite lock contention and deadlocks caused by thread-hopping continuation re-entries across Android coroutine thread pools and Darwin Grand Central Dispatch queues during nested transactions. globs: **/database/**/*.kt, **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-room-sqlite-connection-pool-dispatcher-isolation" --- # KMP Room Multiplatform SQLite Connection Pool and Dispatcher Boundary Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unconfined Room Query Contexts and Cross-Platform Dispatcher Re-entry in Native SQLite Engines ## System Constraints You are a Principal Mobile Architect enforcing strict concurrency and connection pool boundaries in Kotlin Multiplatform (KMP) using AndroidX Room and BundledSQLiteDriver. Enforce platform-isolated query contexts, dedicated single-threaded write pools on Darwin/iOS, bounded parallelism on JVM/Android, and zero-thread-hopping transactions to prevent runtime deadlocks and SQLITE_BUSY or SQLITE_LOCKED crashes. ## Strict Guidelines - Engineers MUST ALWAYS isolate SQLite transaction contexts using a dedicated bounded dispatcher (e.g., `Dispatchers.IO.limitedParallelism(1)` for Native or a dedicated single-threaded executor) when configuring `RoomDatabase.Builder.setQueryCoroutineContext()`. - Engineers MUST NOT allow Room multiplatform transactions to hop threads across unconfined or general-purpose dispatchers (`Dispatchers.Default` or ambient unconfined contexts) between suspension points. - Code SHOULD configure `BundledSQLiteDriver()` uniformly across platforms while setting driver connection configurations via platform-specific factories that respect Darwin thread-local SQLite pointer affinity. - Services MUST wrap multi-statement mutation sequences in Room's idiomatic `useWriterConnection` or `withTransaction` blocks executed strictly on the bounded database dispatcher context. - Components NEVER execute long-running network operations, file serialization, or blocking platform bridge calls inside an active SQLite transaction scope. ## Bad vs Good Implementations ### Room Multiplatform Database Builder Dispatcher Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Assigning Dispatchers.Default allows concurrent continuations to re-enter SQLite connection pointers from different Darwin pthread/GCD workers mid-transaction, leading to connection state corruption and thread synchronization deadlocks. ```kotlin fun createDatabase(builder: RoomDatabase.Builder<AppDatabase>): AppDatabase { // ANTI-PATTERN: Using global Dispatchers.Default or unconfined coroutine contexts. // On iOS (Darwin/Native), SQLite write transactions distributed across arbitrary GCD threads // cause SQLITE_BUSY/LOCKED errors, thread ownership violations, and continuation deadlocks. return builder .setDriver(BundledSQLiteDriver()) .setQueryCoroutineContext(Dispatchers.Default) .build() } ``` #### Production Standard (Correct) > **Standard**: Configuring a dedicated bounded dispatcher ensures deterministic thread scheduling for SQLite operations and prevents unconstrained GCD thread explosion on Darwin while keeping the driver thread-safe. ```kotlin fun createDatabase( builder: RoomDatabase.Builder<AppDatabase>, databaseDispatcher: CoroutineContext = Dispatchers.IO.limitedParallelism(4) ): AppDatabase { // PRODUCTION FIX: Explicitly bind the database execution boundary to a dedicated, // bounded dispatcher. Prevents thread-hopping across Darwin GCD workers and // bounds the connection pool to prevent thread exhaustion on JVM/Android. return builder .setDriver(BundledSQLiteDriver()) .setQueryCoroutineContext(databaseDispatcher) .build() } ``` ### Cross-Platform Transaction Isolation and Thread Hopping Prevention #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Suspension inside a transaction for remote networking holds SQLite write locks open indefinitely, and context-switching to Dispatchers.Default causes resumption on unexpected native threads, provoking deadlocks with other waiting transactions. ```kotlin suspend fun syncEntities(dao: ItemDao, networkApi: ApiClient) { // ANTI-PATTERN: Performing I/O network operations inside a database transaction // while switching coroutine contexts mid-transaction. dao.withTransaction { val items = dao.getPendingUploads() val result = withContext(Dispatchers.Default) { networkApi.postItems(items) // Network latency holds open SQLite lock } dao.markUploaded(result.ids) } } ``` #### Production Standard (Correct) > **Standard**: Isolating network I/O from SQLite transactions minimizes lock hold time and ensures that database transactions execute continuously on the allocated database dispatcher without foreign suspension points. ```kotlin suspend fun syncEntities(dao: ItemDao, networkApi: ApiClient, dbDispatcher: CoroutineDispatcher) { // PRODUCTION FIX: Isolate the network payload fetch outside the database transaction, // execute database mutations strictly on the dedicated database dispatcher context. val pending = withContext(dbDispatcher) { dao.getPendingUploads() } val result = networkApi.postItems(pending) withContext(dbDispatcher) { dao.markUploaded(result.ids) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Room Multiplatform SQLite Connection Pool and Dispatcher Boundary Guardrail

KMP Room Multiplatform SQLite Connection Pool and Dispatcher Boundary Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict asynchronous dispatcher isolation and connection pool boundary configuration across Android and iOS/Darwin runtimes in Room Multiplatform. Prevents catastrophic SQLite lock contention and deadlocks caused by thread-hopping continuation re-entries across Android coroutine thread pools and Darwin Grand Central Dispatch queues during nested transactions. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unconfined Room Query Contexts and Cross-Platform Dispatcher Re-entry in Native SQLite Engines Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unconfined Room Query Contexts and Cross-Platform Dispatcher Re-entry in Native SQLite Engines	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS isolate SQLite transaction contexts using a dedicated bounded dispatcher (e.g., `Dispatchers.IO.limitedParallelism(1)` for Native or a dedicated single-threaded executor) when configuring `RoomDatabase.Builder.setQueryCoroutineContext()`.

Engineers MUST ALWAYS isolate SQLite transaction contexts using a dedicated bounded dispatcher (e.g., `Dispatchers.IO.limitedParallelism(1)` for Native or a dedicated single-threaded executor) when configuring `RoomDatabase.Builder.setQueryCoroutineContext()`.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.