Room 3.0

Declarar dependências

Para inserir uma dependência no 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 mais informações sobre como usar o plug-in KSP, consulte a documentação de início rápido do 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, no arquivo de build de nível superior do Gradle, defina o plug-in e a versão dele.

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 vai 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 sabor, por exemplo, schemas/flavorOneDebug/com.package.MyDatabase/1.json. Esses arquivos precisam ser marcados 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-alpha04

6 de maio de 2026

Lançamento de androidx.room3:room3-*:3.0.0-alpha04. A versão 3.0.0-alpha04 contém essas confirmações (link em inglês).

Mudanças na API

• Adição de APIs para configurar o pool de conexões do Room. As funções do builder setSingleConnectionPool() e setMultipleConnectionPool() podem ser usadas para controlar a quantidade máxima de conexões que o Room vai abrir para o banco de dados. (I9700d, b/438041176, b/432820350)
• Remoção do DatabaseConfiguration do Room da API pública, já que nenhuma outra API pública fazia referência à configuração. (I5f1e9, b/438041176)

Correções de bugs

• Restrição de destinos da Web para usar um único pool de conexões para evitar problemas de 'banco de dados bloqueado' que surgem com o OPFS (b/496255935).
• Tentativa de corrigir (novamente) um erro "Método muito grande" que ocorre devido ao Room gerar um onValidateSchema muito grande. A função é dividida com base na quantidade de instruções, mas a medição não é precisa. Se você ainda encontrar esse erro, ajuste a quantidade de instruções que o Room vai contar para uma divisão usando a opção do processador de anotações room.validationSplitSize. O valor padrão está definido como 300 instruções. Portanto, use um número menor se o problema ainda estiver presente (b/493708172).

Versão 3.0.0-alpha03

8 de abril de 2026

Lançamento de androidx.room3:room3-*:3.0.0-alpha03. A versão 3.0.0-alpha03 contém essas confirmações (link em inglês).

Mudanças na API

• Tornar público o construtor sem argumentos de RoomDatabase para evitar um aviso do Lint quando o construtor for referenciado na declaração @Database. (I9bac2, b/494722261)
• Adição de uma versão de Room.inMemoryDatabaseBuilder e Room.databaseBuilder que não usa um contexto do Android. A necessidade de um contexto foi bastante reduzida no Room 3.0. Portanto, torná-lo um valor opcional para o builder permite criar bancos de dados na memória com mais facilidade no código comum. (I5d502, b/438041176)

Correções de bugs

• Correção de um erro de 'código muito grande' no código gerado pela JVM e pelo Android quando o onValidateSchema corpo da função era muito grande (b/493708172).

Versão 3.0.0-alpha02

25 de março de 2026

Lançamento de androidx.room3:room3-*:3.0.0-alpha02. A versão 3.0.0-alpha02 contém essas confirmações (link em inglês).

Novos recursos

• Suporte ao FTS5:adição de suporte ao FTS5 no Room pela anotação @Fts5. Isso inclui novas constantes para tokenizadores FTS5 (TOKENIZER_ASCII e TOKENIZER_TRIGRAM) e uma enumeração para a opção "detalhe" do FTS (FULL, COLUMN, e NONE). (I90934, b/146824830)
• Destinos de paginação do Room:adição de destinos js, wasmJs, tvOS e watchOS ao room3-paging. (Icffd3, b/432783733)

Mudanças na API

• **`clearAllTables()` multiplataforma**clearAllTables():`clearAllTables()` comum, tornando-o disponível em todas as plataformas.clearAllTables() Ele também foi convertido em uma função suspend. (I434ae, b/322846465)
• Migração destrutiva:adição de um valor de parâmetro padrão a dropAllTables nas APIs fallbackToDestructiveMigration. (Ica88b, b/438041176)

• Mudanças experimentais na API :

  1. Movimentação de @ExperimentalRoomApi para room-common para permitir que APIs baseadas em anotações sejam marcadas como experimentais.

  2. Adição de um RoomWarning experimental para suprimir o requisito de @ConstructedBy em uma declaração de banco de dados do Room. Nesse caso, DatabaseConstructor não será gerado, e uma implementação de fábrica precisa ser fornecida pela DatabaseBuilder. (If5443)

Correções de bugs

• Fonte de paginação:atualização de PagingSourceDaoReturnTypeConverter para indicar corretamente que a função de conversão é destinada a consultas READ. (I3b067, b/139872302)

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 APIs de anotação principais são mantidas iguais aos componentes principais:

• Uma classe abstrata que estende androidx.room3.RoomDatabase e é anotada com @Database é o ponto de entrada para o processador de anotações do 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 momento da 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 o Room ainda é relevante para o Room 3.0.

As principais diferenças 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 androidx.room3:room3-sqlite-wrapper.
• Todas as operações de banco de dados agora são baseadas em APIs de corrotinas.
• Geração de código Kotlin apenas.
• O Kotlin Symbol Processing (KSP) é obrigatório.

Além das mudanças interruptivas, o Room 3.0 oferece 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 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.

Sem APIs SupportSQLite

O Room 3.0 é totalmente apoiado pelas 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, juntamente com a API para receber um SupportSQLiteOpenHelper, foram removidas. Agora, um SQLiteDriver é necessá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 que tem um SQLiteConnection como argumento. Essas 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 estava sendo usado em um projeto KMP, a migração para a versão 3.0 é mais simples, pois envolve principalmente a atualização de referências de importação. Caso contrário, a mesma estratégia de migração do Room no Android para KMP se aplica. Consulte o Guia de migração do KMP do Room.

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 primeiro

Para evoluir melhor a biblioteca, o Room 3.0 só gera código Kotlin e é apenas um Kotlin Symbol Processor (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. O 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 de vários módulos em que o uso do Room seja 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 e, mais especificamente, as funções DAO precisam ser de suspensão, a menos que estejam retornando um tipo reativo, como um Flow ou um tipo de retorno de 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 no Room 3.0 são baseadas em Flow, InvalidationTracker.Observer é removido junto com as APIs relevantes addObserver e removeObserver. O mecanismo para reagir à operação do banco de dados é por meio de fluxos de corrotinas 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 à Web

A versão 3.0 do Room adiciona JavaScript e WasmJs como destinos 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 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 relacionados à 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 maior conveniência, 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 relacionadas à Web, já que as APIs são declarações esperadas / reais que vão chamar a variante certa com base nas plataformas. Essas são as APIs usadas pelo ambiente de execução do Room e permitem o uso do driver 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 worker da Web 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, link em inglês). Para instanciar o driver é necessário um worker que implemente um protocolo de comunicação simples. O protocolo é descrito no WebWorkerSQLiteDriver KDoc.

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

Consulte o projeto do GitHub a seguir (link em inglês) que demonstra o uso de um 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, tornando a configuração da Web mais simples.

Tipos de retorno de DAO personalizados

Várias integrações de tipo de retorno de DAO, como as do RxJava e da paginação, foram transformadas para usar uma nova API no Room 3.0 chamada de conversores de tipo de retorno de DAO. Uma função de conversor de tipo de retorno de DAO (@DaoReturnTypeConverter) permite transformar o resultado de uma função 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 pelas @DaoReturnTypeConverters anotações nas @Database ou @Dao declarações.

Por exemplo, para que uma consulta 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 de 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 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 na quantidade de parâmetros que ela precisa ter e nos tipos. Os parâmetros possíveis são:

• db: RoomDatabase: (opcional) fornece acesso à instância RoomDatabase, 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 combinados com a API InvalidationTracker.createFlow() do Room.
• rawQuery: RoomRawQuery: (opcional) contém no momento da 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 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 @DaoReturnTypeConverter API.