Transacciones y escrituras: @Transaction, upsert y lotes

Una escritura aislada en SQLite es engañosamente cara: no por el coste de insertar una fila, sino por el fsync que garantiza que esa fila sobrevive a un corte de corriente. Mil inserciones sueltas son mil promesas de durabilidad; mil inserciones dentro de una transacción son una sola. Esa asimetría, y no el SQL, es lo que gobierna el rendimiento de escritura en una app Android. A su lado convive un segundo asunto igual de decisivo: qué puede ocurrir en paralelo dentro de Room y qué queda inevitablemente serializado.

Atomicidad: @Transaction y el todo o nada

Una transacción agrupa varias sentencias en una unidad indivisible: o se aplican todas o no se aplica ninguna. En Room, un método de DAO anotado con @Transaction envuelve su cuerpo entero, incluidas las llamadas a otros métodos del mismo DAO.

@Dao
interface PedidoDao {

    @Insert
    suspend fun insertarPedido(pedido: Pedido): Long

    @Insert
    suspend fun insertarLineas(lineas: List<LineaPedido>)

    @Query("UPDATE stock SET unidades = unidades - :n WHERE producto_id = :id")
    suspend fun descontar(id: Long, n: Int)

    @Transaction
    suspend fun registrar(pedido: Pedido, lineas: List<LineaPedido>) {
        val id = insertarPedido(pedido)
        insertarLineas(lineas.map { it.copy(pedidoId = id) })
        lineas.forEach { descontar(it.productoId, it.unidades) }
    }
}

Sin @Transaction, un fallo al descontar stock dejaría un pedido registrado sin su descuento: la base quedaría en un estado que ninguna regla de negocio contempla. Con ella, cualquier excepción provoca un rollback completo y la base vuelve exactamente a donde estaba.

Dos matices que se olvidan a menudo. El primero: la transacción termina cuando el método retorna, así que lanzar trabajo asíncrono dentro y no esperarlo lo deja fuera de la garantía. El segundo: @Transaction también sirve para lecturas compuestas, y de hecho es obligatorio cuando una consulta con @Relation ejecuta varias sentencias que deben ver la misma instantánea.

Conflictos, upsert y escritura en lote

Insertar una fila cuya clave primaria o índice único ya existe es un conflicto, y hay que decidir qué hacer. @Insert acepta una estrategia; @Upsert resuelve el caso más común sin obligarte a elegir.

@Dao
interface ArticuloDao {

    @Insert(onConflict = OnConflictStrategy.IGNORE)
    suspend fun insertarSiFalta(articulos: List<Articulo>): List<Long>

    @Upsert
    suspend fun guardar(articulos: List<Articulo>)

    @Transaction
    suspend fun sincronizar(remotos: List<Articulo>, vigentes: List<Long>) {
        guardar(remotos)
        borrarFuera(vigentes)
    }

    @Query("DELETE FROM articulos WHERE id NOT IN (:vigentes)")
    suspend fun borrarFuera(vigentes: List<Long>)
}

La diferencia entre REPLACE y @Upsert es la trampa más costosa de este nivel. REPLACE ejecuta un borrado seguido de una inserción; si otra tabla referencia esa fila con onDelete = CASCADE, sus hijos desaparecen aunque el objetivo fuera solo actualizar dos campos. @Upsert hace un UPDATE real sobre la fila existente y no dispara ningún borrado.

Sobre el lote: los métodos anotados aceptan colecciones, y esa forma es siempre preferible al bucle. Room ejecuta las inserciones sobre la misma sentencia preparada y, cuando el método es @Transaction o forma parte de uno, dentro de una sola transacción.

// Mal: mil transacciones implícitas, mil promesas de durabilidad.
articulos.forEach { dao.guardarUno(it) }

// Bien: una transacción, una sentencia preparada reutilizada.
dao.guardar(articulos)

La diferencia no es marginal. Cada transacción implícita fuerza al menos una sincronización con el almacenamiento; agrupar mil escrituras convierte mil sincronizaciones en una y suele mejorar el tiempo total en uno o dos órdenes de magnitud.

Concurrencia real: WAL, muchos lectores, un escritor

Room abre la base en modo WAL siempre que la plataforma lo permite, y ese detalle define todo el modelo de concurrencia.

flowchart TD
A[Modo WAL activo] --> B[Escrituras van al fichero de log]
A --> C[Lecturas ven la ultima version confirmada]
B --> D{Cuantos escritores a la vez}
D -->|Uno solo| E[El resto espera su turno]
C --> F{Cuantos lectores a la vez}
F -->|Varios| G[Lectura paralela sin bloquear al escritor]
E --> H[Checkpoint mueve el log a la base principal]
G --> H
style G fill:#a6e3a1,color:#11111b
style E fill:#f9e2af,color:#11111b

En WAL, las escrituras se anexan a un fichero de registro separado y los lectores siguen viendo la última versión confirmada sin bloquearse. Esto permite lecturas concurrentes durante una escritura, algo imposible en el modo por defecto de SQLite. Lo que WAL no cambia es la regla fundamental: hay un único escritor a la vez.

Room refleja esa asimetría en su ejecución interna: usa un ejecutor con varios hilos para consultas de lectura y un único hilo para transacciones de escritura. Por eso lanzar diez corrutinas de escritura en paralelo no acelera nada; solo llena una cola. La concurrencia útil está en el lado de la lectura.