Room 3.0

Declarar dependências

Para adicionar uma dependência do Room3, adicione o repositório Maven do Google ao seu projeto. Leia Repositório Maven do Google para ver mais informações.

Adicione as dependências dos artefatos necessários no arquivo build.gradle para seu app ou módulo:

dependencies {
    val room_version = ""

    implementation("androidx.room3:room3-runtime:$room_version")
    ksp("androidx.room3:room3-compiler:$room_version")
}

dependencies {
    def room_version = ""

    implementation "androidx.room3:room3-runtime:$room_version"

    ksp "androidx.room3:room3-compiler:$room_version"
}

Para informações sobre como usar o plug-in KSP, consulte a documentação de início rápido da KSP.

Para ver mais informações sobre dependências, consulte Adicionar dependências de compilação.

Usar o plug-in do Gradle para Room

Você pode usar o plug-in do Gradle para Room para configurar opções do compilador do Room. O plug-in configura o projeto para que os esquemas gerados (que são uma saída das tarefas de compilação e são consumidos para migrações automáticas) sejam configurados corretamente para ter builds reproduzíveis e armazenáveis em cache.

Para adicionar o plug-in, defina o plug-in e a versão dele no arquivo de build do Gradle de nível superior.

plugins {
    id 'androidx.room3' version "$room_version" apply false
}

plugins {
    id("androidx.room3") version "$room_version" apply false
}

No arquivo de build do Gradle no nível do módulo, aplique o plug-in e use a extensão room3.

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

room3 {
    schemaDirectory("$projectDir/schemas")
}

É necessário definir um schemaDirectory ao usar o plug-in do Gradle para Room. Isso configurará o compilador do Room e as várias tarefas de compilação e back-ends (kotlinc, KSP) para gerar arquivos de esquema em pastas com variações, por exemplo schemas/flavorOneDebug/com.package.MyDatabase/1.json. Esses arquivos precisam ser verificados no repositório para serem usados na validação e nas migrações automáticas.

Feedback

Seu feedback ajuda a melhorar o Jetpack. Avise se você descobrir novos problemas ou tiver ideias para melhorar esta biblioteca. Consulte os problemas conhecidos nesta biblioteca antes de criar um novo. Adicione seu voto a um problema clicando no botão de estrela.

Criar novo problema

Consulte a documentação do Issue Tracker para saber mais.

Versão 3.0

Versão 3.0.0-alpha01

11 de março de 2026

Lançamento de androidx.room3:room3-*:3.0.0-alpha01.

O Room 3.0 (pacote androidx.room3) é uma atualização de versão principal do pacote Room 2.x (androidx.room) que se concentra no Kotlin Multiplatform (KMP).

As principais APIs de anotação e os componentes principais permanecem os mesmos:

• Uma classe abstrata que estende androidx.room3.RoomDatabase e é anotada com @Database é o ponto de entrada para o processador de anotações da Room.
• A declaração de banco de dados tem uma ou mais classes de dados que descrevem o esquema do banco de dados e são anotadas com @Entity.
• As operações de banco de dados são definidas em declarações @Dao que contêm funções de consulta cujas instruções SQL são definidas pela anotação @Query.
• No tempo de execução, a implementação do banco de dados pode ser obtida por um RoomDatabase.Builder, que também é usado para configurar o banco de dados.

A maior parte da documentação no guia Salvar dados em um banco de dados local usando Room ainda é relevante para o Room 3.0.

As principais diferenças incompatíveis entre o Room 2.x são as seguintes:

• Novo pacote, androidx.room3.
• As APIs SupportSQLite não são mais compatíveis, a menos que você esteja usando o androidx.room3:room3-sqlite-wrapper.
• Todas as operações de banco de dados agora são baseadas em APIs de corrotina.
• Geração de código Kotlin apenas.
• O Kotlin Symbol Processing (KSP) é obrigatório.

Além das mudanças significativas, o Room 3.0 traz novas funcionalidades em comparação com a versão 2.x:

• Suporte a JS e WasmJS
• Tipos de retorno de DAO personalizados

Novo pacote

Para evitar problemas de compatibilidade com implementações do Room 2.x e para bibliotecas com dependências transitivas do Room (por exemplo, WorkManager), o Room 3.0 reside em um novo pacote, o que significa que ele também tem um novo grupo do Maven e IDs de artefato. Por exemplo, androidx.room:room-runtime se tornou androidx.room3:room3-runtime e classes como androidx.room.RoomDatabase agora estão localizadas em androidx.room3.RoomDatabase.

Nenhuma API SupportSQLite

O Room 3.0 é totalmente compatível com as APIs SQLiteDriver e não faz mais referência a tipos SupportSQLite, como SupportSQLiteDatabase ou tipos do Android, como Cursor. Essa é a mudança mais significativa entre o Room 3.0 e o 2.x, já que as APIs RoomDatabase que espelhavam SupportSQLiteDatabase, além da API para receber um SupportSQLiteOpenHelper, foram removidas. Agora, um SQLiteDriver é obrigatório para criar um RoomDatabase.

Por exemplo, as APIs para operações diretas de banco de dados são substituídas por equivalentes de driver:

// Room 2.x
roomDatabase.runInTransaction { ... }

// Room 3.x
roomDatabase.withWriteTransaction { ... }

// Room 2.x
roomDatabase.query("SELECT * FROM Song").use { cursor -> ... }

// Room 3.x
roomDatabase.useReaderConnection { connection ->
  connection.usePrepared("SELECT * FROM Song") { stmt -> ... }
}

As APIs de callback que tinham um SupportSQLiteDatabase como argumento também foram substituídas pela API equivalente com um SQLiteConnection como argumento. São funções de callback de migrações, como Migration.onMigrate() e AutoMigrationSpec.onPostMigrate(), além de callbacks de banco de dados, como RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen() etc.

Se o Room estiver sendo usado em um projeto KMP, a migração para a versão 3.0 será mais simples, já que envolve principalmente a atualização de referências de importação. Caso contrário, a mesma estratégia de migração do Room somente para Android para KMP se aplica. Consulte o guia de migração do Room KMP.

Wrapper SupportSQLite

O Room 3.x preserva o wrapper SupportSQLite criado na versão 2.x para facilitar as migrações e agora está localizado em um novo artefato androidx.room3:room3-sqlite-wrapper. A API de compatibilidade permite converter um RoomDatabase em um SupportSQLiteDatabase. As invocações de roomDatabase.openHelper.writableDatabase podem ser substituídas por roomDatabase.getSupportWrapper().

Kotlin e corrotinas em primeiro lugar

Para melhorar a evolução da biblioteca, o Room 3.0 gera apenas código Kotlin e é apenas um processador de símbolos Kotlin (KSP). Em comparação com o Room 2.x, não há geração de código Java, e a configuração do processador de anotações via KAPT ou JavaAP não é mais possível no Room 3.0. A KSP pode processar fontes Java, e o compilador do Room vai gerar código para banco de dados, entidades ou DAOs cujas declarações de origem estejam em Java. Recomendamos ter um projeto com vários módulos em que o uso do Room esteja concentrado e o plug-in do Gradle para Kotlin e o KSP possam ser aplicados sem afetar o restante da base de código.

O Room 3.0 também exige o uso de corrotinas. Mais especificamente, as funções DAO precisam ser de suspensão, a menos que retornem um tipo reativo, como um Flow ou um tipo de retorno DAO personalizado. As APIs do Room para realizar operações de banco de dados também são funções de suspensão, como RoomDatabase.useReaderConnection e RoomDatabase.useWriterConnection.

Ao contrário do Room 2.x, não é mais possível configurar um RoomDatabase com um Executor. Em vez disso, um CoroutineContext e um dispatcher podem ser fornecidos pelo builder do banco de dados.

As APIs InvalidationTracker na Room 3.0 são baseadas em Flow. O InvalidationTracker.Observer foi removido junto com as APIs relevantes addObserver e removeObserver. O mecanismo para reagir à operação do banco de dados é por fluxos de corrotina que podem ser criados pela API createFlow() no InvalidationTracker.

Exemplo de uso:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
    return db.invalidationTracker.createFlow("Artist").map { _ ->
        val artists = artistsDao.getAllArtists()
        val tours = tourService.fetchStates(artists.map { it.id })
        associateTours(artists, tours, from, to)
    }
}

Suporte na Web

A versão 3.0 do Room adiciona JavaScript e WasmJs como destinos do KMP. Combinado com o lançamento das interfaces SQLiteDriver (androidx.sqlite:sqlite) que também têm como destino JavaScript e WasmJs, e um novo driver WebWorkerSQLiteDriver localizado no novo artefato androidx.sqlite:sqlite-web, é possível usar o Room em um código comum que tem como destino todas as principais plataformas KMP.

Devido à natureza assíncrona das plataformas da Web, as APIs do Room que usavam SQLiteStatement como argumento agora são funções de suspensão. Exemplos dessas funções são Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() e outras. Nas APIs de driver, as APIs assíncronas são comuns em todas as plataformas, e as síncronas são comuns para destinos não Web. Portanto, um projeto que não tem como destino a Web pode continuar usando as APIs síncronas (SQLiteDriver.open(), SQLiteConnection.prepare() e SQLiteStatement.step()) em código comum. Enquanto isso, um projeto que tem como destino apenas a Web precisa usar as APIs assíncronas (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() e SQLiteStatement.stepAsync()).

Para facilitar, o pacote androidx.sqlite também adicionou funções de extensão de suspensão com os nomes síncronos das APIs mencionadas (com a adição de SQLiteConnection.executeSQL). Essas APIs são recomendadas quando o projeto tem como destino plataformas da Web e não da Web, já que são declarações de expectativa / real que vão chamar a variante certa com base nas plataformas. Essas são as APIs que o tempo de execução do Room usa e que permitem o uso de drivers em código comum para todas as plataformas compatíveis.

Exemplo de uso:

import androidx.sqlite.executeSQL
import androidx.sqlite.step

roomDatabase.useWriterConnection { connection ->
    val deletedSongs = connection.usePrepared(
        "SELECT count(*) FROM Song"
    ) { stmt ->
        stmt.step()
        stmt.getLong(0)
    }
    connection.executeSQL("DELETE FROM Song")
    deletedSongs
}

O WebWorkerSQLiteDriver é uma implementação de um SQLiteDriver que se comunica com um Web Worker para realizar operações de banco de dados fora da linha de execução principal e permite armazenar o banco de dados no Origin Private File System (OPFS). Para instanciar o driver, é necessário um worker que implemente um protocolo de comunicação simples. O protocolo é descrito no KDoc WebWorkerSQLiteDriver.

No momento, o WebWorkerSQLiteDriver não é fornecido com um worker padrão que implementa o protocolo de comunicação. No entanto, como exemplo, a base de código androidx contém uma implementação de worker que pode ser usada no seu projeto. Ele usa o WASM do SQLite e armazena o banco de dados no OPFS. O exemplo de worker é publicado como um pacote NPM local e, graças ao suporte do Kotlin para dependências do NPM, é possível criar um pequeno módulo KMP para atender ao worker.

Confira o projeto do GitHub a seguir, que demonstra o uso de um service worker da Web local para o Room.

Depois que um worker é configurado no projeto, a configuração do Room para a Web é semelhante a outras plataformas:

fun createDatabase(): MusicDatabase {
    return Room.databaseBuilder<MusicDatabase>("music.db")
        .setDriver(WebWorkerSQLiteDriver(createWorker()))
        .build()
}

fun createWorker() =
    Worker(js("""new URL("sqlite-web-worker/worker.js", import.meta.url)"""))

Uma versão futura do driver da Web pode conter um worker padrão publicado no NPM, simplificando a configuração da Web.

Tipos de retorno de DAO personalizados

Várias integrações de tipo de retorno de DAO, como as do RxJava e da Paging, foram transformadas para usar uma nova API no Room 3.0 chamada de conversores de tipo de retorno de DAO. Uma função de conversão de tipo de retorno de DAO (@DaoReturnTypeConverter) permite transformar o resultado de uma função de DAO em um tipo personalizado definido pela função anotada. Essas funções permitem participar do código gerado pelo Room, que transforma resultados de consultas em objetos de dados. As classes que contêm conversores de tipo de retorno de DAO precisam ser registradas usando as anotações @DaoReturnTypeConverters nas declarações @Database ou @Dao.

Por exemplo, para que uma consulta de DAO retorne um PagingSource, a classe de conversor localizada em androidx.room3:room3-paging precisa ser registrada:

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song)
    fun getSongsPaginated(): PagingSource<Int, Song>
}

As integrações atuais foram movidas para conversores de tipo de retorno de DAO:

Assim como os conversores de tipo de coluna, os conversores de tipo de retorno do DAO podem ser definidos pelo aplicativo. Por exemplo, um aplicativo pode declarar um @DaoReturnTypeConverter para o tipo da Web kotlin.js.Promise.

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

O conversor acima permite que as funções de consulta do DAO retornem Promise:

@Dao
@DaoReturnTypeConverters(PromiseDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song")
    fun getAllSongs(): Promise<List<Song>>
}

Uma função @DaoReturnTypeConverter tem alguns requisitos quanto à quantidade de parâmetros e aos tipos deles. Os parâmetros possíveis são:

• db: RoomDatabase: (opcional) fornece acesso à instância RoomDatabase, o que pode ser útil para realizar outras operações de banco de dados ou acessar o escopo da corrotina.
• tableNames: Array<String>: (opcional) contém as tabelas acessadas da consulta, útil para oferecer suporte a tipos observáveis / reativos quando combinado com a API InvalidationTracker.createFlow() do Room.
• rawQuery: RoomRawQuery: (opcional) contém no tempo de execução uma instância da consulta, permitindo transformações como a estratégia LIMIT / OFFSET implementada pelo PagingSourceDaoReturnTypeConverter.
• executeAndConvert: suspend () -> T: (obrigatório) a função gerada pelo Room que vai executar a consulta e analisar o resultado dela em objetos de dados.

Para mais informações sobre os requisitos para criar um conversor de tipo de retorno de DAO, consulte o KDoc na API @DaoReturnTypeConverter.