Room 3.0

  
La libreria di persistenza Room fornisce un livello di astrazione su SQLite per consentire un accesso al database più affidabile, sfruttando al contempo tutta la potenza di SQLite.
Ultimo aggiornamento Release stabile Candidato per la release Release beta Release alpha
25 marzo 2026 - - - 3.0.0-alpha02

Dichiara le dipendenze

Per aggiungere una dipendenza da Room3, devi aggiungere il repository Maven di Google al tuo progetto. Per saperne di più, consulta il repository Maven di Google.

Aggiungi le dipendenze per gli artefatti necessari nel file build.gradle per la tua app o il tuo modulo:

Kotlin

dependencies {
    val room_version = ""

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

Groovy

dependencies {
    def room_version = ""

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

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

Per informazioni sull'utilizzo del plug-in KSP, consulta la documentazione della Guida rapida di KSP.

Per saperne di più sulle dipendenze, consulta Aggiungere dipendenze di build.

Utilizza il plug-in Gradle di Room

Puoi utilizzare il plug-in Gradle di Room per configurare le opzioni del compilatore Room. Il plug-in configura il progetto in modo che gli schemi generati (che sono un output delle attività di compilazione e vengono utilizzati per le migrazioni automatiche) siano configurati correttamente per avere build riproducibili e memorizzabili nella cache.

Per aggiungere il plug-in, definisci il plug-in e la relativa versione nel file della build Gradle di primo livello.

Groovy

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

Kotlin

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

Nel file della build Gradle a livello di modulo, applica il plug-in e utilizza l'estensione room3.

Groovy

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

Kotlin

plugins {
    id("androidx.room3")
}

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

Quando utilizzi il plug-in Gradle di Room, devi impostare un schemaDirectory. In questo modo, il compilatore Room e le varie attività di compilazione e i relativi backend (kotlinc, KSP) verranno configurati per generare file di schema nelle cartelle con flavor, ad esempio schemas/flavorOneDebug/com.package.MyDatabase/1.json. Questi file devono essere archiviati nel repository per essere utilizzati per la convalida e le migrazioni automatiche.

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Facci sapere se riscontri nuovi problemi o hai idee per migliorare questa raccolta. Prima di segnalare un nuovo problema, dai un'occhiata ai problemi esistenti in questa raccolta. Puoi aggiungere il tuo voto a un problema esistente facendo clic sul pulsante a forma di stella.

Crea un nuovo problema

Per saperne di più, consulta la documentazione di Issue Tracker.

Versione 3.0

Versione 3.0.0-alpha02

25 marzo 2026

androidx.room3:room3-*:3.0.0-alpha02 è stato rilasciato. La versione 3.0.0-alpha02 contiene questi commit.

Nuove funzionalità

  • Supporto di FTS5: è stato aggiunto il supporto di FTS5 a Room tramite l'annotazione @Fts5. Sono incluse nuove costanti per i tokenizer FTS5 (TOKENIZER_ASCII e TOKENIZER_TRIGRAM) e un'enumerazione per l'opzione FTS "detail" (FULL, COLUMN, e NONE). (I90934, b/146824830)
  • Target di paginazione di Room: sono stati aggiunti i target js, wasmJs, tvOS e watchOS a room3-paging. (Icffd3, b/432783733)

Modifiche alle API

  • Multipiattaforma clearAllTables(): è stata resa comune la funzione clearAllTables(), rendendola disponibile su tutte le piattaforme. È stata anche convertita in una funzione suspend. (I434ae, b/322846465)
  • Migrazione distruttiva: è stato aggiunto un valore parametro predefinito a dropAllTables nelle API fallbackToDestructiveMigration. (Ica88b, b/438041176)

  • Modifiche alle API sperimentali:

    1. @ExperimentalRoomApi è stato spostato in room-common per consentire di contrassegnare le API basate su annotazioni come sperimentali.

    2. È stato aggiunto un RoomWarning sperimentale per eliminare il requisito di @ConstructedBy in una dichiarazione di database Room. In questo caso, DatabaseConstructor non verrà generato e un'implementazione di factory deve essere fornita tramite DatabaseBuilder. (If5443)

Correzioni di bug

  • Origine di paginazione: è stato aggiornato PagingSourceDaoReturnTypeConverter per indicare correttamente che la relativa funzione di conversione è destinata alle query READ. (I3b067, b/139872302)

Versione 3.0.0-alpha01

11 marzo 2026

androidx.room3:room3-*:3.0.0-alpha01 è stato rilasciato.

Room 3.0 (pacchetto androidx.room3) è un aggiornamento della versione principale del pacchetto Room 2.x (androidx.room) incentrato su Kotlin Multiplatform (KMP).

Le API di annotazione principali rimangono le stesse, così come i componenti principali:

  • Una classe astratta che estende androidx.room3.RoomDatabase e viene annotata con @Database è il punto di ingresso per il processore di annotazioni di Room.
  • La dichiarazione del database contiene una o più classi di dati che descrivono lo schema del database e sono annotate con @Entity.
  • Le operazioni del database sono definite nelle dichiarazioni @Dao che contengono funzioni di query le cui istruzioni SQL sono definite tramite l'annotazione @Query.
  • In fase di runtime, l'implementazione del database può essere ottenuta tramite un RoomDatabase.Builder, utilizzato anche per configurare il database.

La maggior parte della documentazione della guida Salvare i dati in un database locale utilizzando Room è ancora pertinente a Room 3.0.

Le principali differenze che causano interruzioni tra Room 2.x sono le seguenti:

  • Nuovo pacchetto, androidx.room3.
  • Le API SupportSQLite non sono più supportate, a meno che tu non utilizzi androidx.room3:room3-sqlite-wrapper.
  • Tutte le operazioni del database sono ora basate sulle API Coroutine.
  • Generazione di codice Kotlin.
  • È richiesto Kotlin Symbol Processing (KSP).

Oltre alle modifiche che causano interruzioni, Room 3.0 introduce nuove funzionalità rispetto a 2.x:

  • Supporto di JS e WasmJS
  • Tipi restituiti DAO personalizzati

Nuovo pacchetto

Per evitare problemi di compatibilità con le implementazioni Room 2.x esistenti e per le librerie con dipendenze transitive da Room (ad esempio, WorkManager), Room 3.0 si trova in un nuovo pacchetto, il che significa che ha anche un nuovo gruppo Maven e nuovi ID artefatto. Ad esempio, androidx.room:room-runtime è diventato androidx.room3:room3-runtime e le classi come androidx.room.RoomDatabase si troveranno ora in androidx.room3.RoomDatabase.

Nessuna API SupportSQLite

Room 3.0 è completamente supportato dalle API SQLiteDriver e non fa più riferimento ai tipi SupportSQLite come SupportSQLiteDatabase o ai tipi Android come Cursor. Questa è la modifica più significativa tra Room 3.0 e 2.x, poiché le API RoomDatabase che rispecchiavano SupportSQLiteDatabase insieme all'API per ottenere un SupportSQLiteOpenHelper sono state rimosse. Ora è necessario un SQLiteDriver per creare un RoomDatabase.

Ad esempio, le API per le operazioni dirette del database vengono sostituite dagli equivalenti del 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 -> ... }
}

Anche le API di callback che avevano come argomento un SupportSQLiteDatabase sono state sostituite dalle API equivalenti che hanno un SQLiteConnection come argomento. Si tratta di funzioni di callback di migrazione come Migration.onMigrate() e AutoMigrationSpec.onPostMigrate() insieme a callback di database come RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen() e così via.

Se Room veniva utilizzato in un progetto KMP, la migrazione a 3.0 è più semplice, in quanto comporta principalmente l'aggiornamento dei riferimenti di importazione. In caso contrario, si applica la stessa strategia di migrazione da Room solo per Android a KMP. Consulta la Guida alla migrazione di Room KMP.

Wrapper SupportSQLite

Room 3.x conserva il wrapper SupportSQLite creato in 2.x per semplificare le migrazioni e ora si trova in un nuovo artefatto androidx.room3:room3-sqlite-wrapper. L'API di compatibilità consente di convertire un RoomDatabase in un SupportSQLiteDatabase. Le invocazioni di roomDatabase.openHelper.writableDatabase possono essere sostituite da roomDatabase.getSupportWrapper().

Kotlin e Coroutine prima di tutto

Per migliorare l'evoluzione della libreria, Room 3.0 genera solo codice Kotlin ed è solo un processore di simboli Kotlin (KSP). Rispetto a Room 2.x, non è presente la generazione di codice Java e la configurazione del processore di annotazioni tramite KAPT o JavaAP non è più possibile in Room 3.0. Tieni presente che KSP è in grado di elaborare le origini Java e il compilatore Room genererà codice per database, entità o DAO le cui dichiarazioni di origine sono in Java. È consigliabile avere un progetto multi-modulo in cui l'utilizzo di Room è concentrato e il plug-in Gradle di Kotlin e KSP possono essere applicati senza influire sul resto della codebase.

Room 3.0 richiede anche l'utilizzo di Coroutine e, più in particolare, le funzioni DAO devono essere sospese, a meno che non restituiscano un tipo reattivo, ad esempio un Flow o un tipo restituito DAO personalizzato. Anche le API Room per eseguire operazioni del database sono funzioni di sospensione, come RoomDatabase.useReaderConnection e RoomDatabase.useWriterConnection.

A differenza di Room 2.x, non è più possibile configurare un RoomDatabase con un Executor, ma è possibile fornire un CoroutineContext insieme a un dispatcher tramite il builder del database.

InvalidationTracker API in Room 3.0 sono basate su Flow, InvalidationTracker.Observer viene rimosso insieme alle relative API addObserver e removeObserver. Il meccanismo per reagire all'operazione del database avviene tramite i flussi di coroutine che possono essere creati tramite l'API createFlow() in InvalidationTracker.

Esempio di utilizzo:

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)
    }
}

Supporto web

La release di Room 3.0 aggiunge JavaScript e WasmJs come target KMP. Insieme alla release delle interfacce SQLiteDriver (androidx.sqlite:sqlite) che hanno come target anche JavaScript e WasmJs e un nuovo driver WebWorkerSQLiteDriver che si trova nel nuovo artefatto androidx.sqlite:sqlite-web, è possibile utilizzare Room nel codice comune che ha come target tutte le principali piattaforme KMP.

A causa della natura asincrona delle piattaforme web, le API Room che accettavano SQLiteStatement come argomento sono ora funzioni di sospensione. Esempi di queste funzioni sono Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() e altre. Nelle API del driver, le API asincrone sono comuni su tutte le piattaforme, mentre quelle sincrone sono comuni per i target non web. Pertanto, un progetto che non ha come target il web può continuare a utilizzare le API sincrone (SQLiteDriver.open(), SQLiteConnection.prepare() e SQLiteStatement.step()) nel codice comune. Nel frattempo, un progetto che ha come target solo il web deve utilizzare le API asincrone (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() e SQLiteStatement.stepAsync()).

Per comodità, il pacchetto androidx.sqlite ha aggiunto anche funzioni di estensione di sospensione con i nomi sincroni delle API menzionate (con l'aggiunta di SQLiteConnection.executeSQL). Queste API sono consigliate quando il progetto ha come target sia piattaforme web che non web, poiché le API sono dichiarazioni expect / actual che chiameranno la variante corretta in base alle piattaforme. Queste sono le API utilizzate dal runtime di Room e consentono l'utilizzo del driver nel codice comune per tutte le piattaforme supportate.

Esempio di utilizzo:

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
}

Il WebWorkerSQLiteDriver è un'implementazione di un SQLiteDriver che comunica con un web worker per eseguire l'operazione del database al di fuori del thread principale e consente di archiviare il database nel file system privato di origine (OPFS). Per creare un'istanza del driver è necessario un worker che implementi un semplice protocollo di comunicazione. Il protocollo è descritto nel KDoc di WebWorkerSQLiteDriver.

Al momento, WebWorkerSQLiteDriver non include un worker predefinito che implementa il protocollo di comunicazione, ma, ad esempio, la codebase androidx contiene un'implementazione del worker che può essere utilizzata nel tuo progetto. Utilizza WASM di SQLite's e archivia il database in OPFS. Il worker di esempio viene pubblicato come pacchetto NPM locale e, grazie al supporto di Kotlin per le dipendenze NPM, è possibile creare un piccolo modulo KMP per pubblicare il worker.

Consulta il seguente progetto GitHub che mostra l'utilizzo di un web worker locale per Room.

Una volta configurato un worker nel progetto, la configurazione di Room per il web è simile a quella di altre piattaforme:

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)"""))

Una versione futura del driver web potrebbe contenere un worker predefinito pubblicato in NPM, semplificando la configurazione web.

Tipi restituiti DAO personalizzati

Varie integrazioni di tipi restituiti DAO, come quelle per RxJava e Paging, sono state trasformate per utilizzare una nuova API in Room 3.0 chiamata convertitori di tipi restituiti DAO. Una funzione di conversione del tipo restituito DAO (@DaoReturnTypeConverter) consente di trasformare il risultato di una funzione DAO in un tipo personalizzato definito dalla funzione annotata. Queste funzioni consentono di partecipare al codice generato di Room che trasforma i risultati delle query in oggetti dati. Le classi che contengono convertitori di tipi restituiti DAO devono essere registrate tramite le @DaoReturnTypeConverters annotazioni nelle @Database o @Dao dichiarazioni.

Ad esempio, per fare in modo che una query DAO restituisca un PagingSource, ora è necessario registrare la classe di conversione che si trova in androidx.room3:room3-paging:

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

Le integrazioni esistenti sono state spostate nei convertitori di tipi restituiti DAO:

Tipo restituito Classe di conversione Artefatto
PagingSource PagingSourceDaoReturnTypeConverter androidx.room3:room3-paging
Observable, Flowable, Completable, Single, Maybe RxDaoReturnTypeConverters androidx.room3:room3-rxjava3
ListenableFuture GuavaDaoReturnTypeConverter androidx.room3:room3-guava
LiveData LiveDataDaoReturnTypeConverter androidx.room3:room3-livedata

Come i convertitori di tipi di colonne, i convertitori di tipi restituiti DAO possono essere definiti dall'applicazione. Ad esempio, un'applicazione potrebbe dichiarare un @DaoReturnTypeConverter per il tipo 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() }
    }
}

Il convertitore sopra riportato consente quindi alle funzioni di query DAO di restituire Promise:

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

Una funzione @DaoReturnTypeConverter ha alcuni requisiti per quanto riguarda la quantità di parametri che deve avere e i relativi tipi. I parametri possibili sono:

  • db: RoomDatabase: (facoltativo) fornisce l'accesso all'RoomDatabase istanza, che può essere utile per eseguire operazioni aggiuntive del database o accedere all'ambito della coroutine.
  • tableNames: Array<String>: (facoltativo) contiene le tabelle a cui è stata eseguita l'query, utile per supportare i tipi osservabili / reattivi quando combinati con l'API di Room.InvalidationTracker.createFlow()
  • rawQuery: RoomRawQuery: (facoltativo) contiene in fase di runtime un'istanza della query, consentendo trasformazioni come la strategia LIMIT / OFFSET implementata da PagingSourceDaoReturnTypeConverter.
  • executeAndConvert: suspend () -> T: (obbligatorio) la funzione generata da Room che eseguirà la query e analizzerà il risultato in oggetti dati.

Per saperne di più sui requisiti per la creazione di un convertitore di tipi restituiti DAO, consulta il KDoc dell'@DaoReturnTypeConverter API.