Room 3.0

Déclarer des dépendances

Pour ajouter une dépendance sur Room3, vous devez ajouter le dépôt Maven de Google à votre projet. Pour en savoir plus, consultez la section Dépôt Maven de Google.

Ajoutez les dépendances des artefacts dont vous avez besoin dans le fichier build.gradle de votre application ou module :

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

Pour en savoir plus sur l'utilisation du plug-in KSP, consultez la documentation de démarrage rapide de KSP.

Pour en savoir plus sur les dépendances, consultez la page Ajouter des dépendances de compilation.

Utiliser le plug-in Room Gradle

Vous pouvez utiliser le plug-in Room Gradle pour configurer les options du compilateur Room. Le plug-in configure le projet de sorte que les schémas générés (qui sont une sortie des tâches de compilation et sont utilisés pour les migrations automatiques) soient correctement configurés pour avoir des builds reproductibles et pouvant être mis en cache.

Pour ajouter le plug-in, dans le fichier de compilation Gradle de premier niveau, définissez le plug-in et sa version.

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

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

Dans le fichier de compilation Gradle au niveau du module, appliquez le plug-in et utilisez l'extension room3.

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

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

La définition d'un schemaDirectory est obligatoire lorsque vous utilisez le plug-in Room Gradle. Cela configure le compilateur Room, les différentes tâches de compilation et ses backends (kotlinc, KSP) pour générer des fichiers de schéma dans des dossiers spécifiques, par exemple schemas/flavorOneDebug/com.package.MyDatabase/1.json. Ces fichiers doivent être enregistrés dans le dépôt pour être utilisés à des fins de validation et de migration automatique.

Commentaires

Vos commentaires nous aident à améliorer Jetpack. N'hésitez pas à nous contacter si vous découvrez de nouveaux problèmes ou si vous avez des idées pour améliorer cette bibliothèque. Veuillez consulter les problèmes existants de cette bibliothèque avant d'en signaler un nouveau. Vous pouvez ajouter votre vote à un problème existant en cliquant sur le bouton en forme d'étoile.

Signaler un nouveau problème

Pour en savoir plus, consultez la documentation sur l'outil Issue Tracker.

Version 3.0

Version 3.0.0-alpha02

25 mars 2026

Publication d'androidx.room3:room3-*:3.0.0-alpha02. Liste des commits de la version 3.0.0-alpha02 .

Nouvelles fonctionnalités

• Compatibilité avec FTS5 : ajout de la compatibilité avec FTS5 à Room via l'annotation @Fts5. Cela inclut de nouvelles constantes pour les tokenizers FTS5 (TOKENIZER_ASCII et TOKENIZER_TRIGRAM) et une énumération pour l'option FTS 'detail' (FULL, COLUMN, et NONE). (I90934, b/146824830)
• Cibles de pagination Room : ajout des cibles js, wasmJs, tvOS et watchOS à room3-paging. (Icffd3, b/432783733)

Modifications apportées à l'API

• Multiplate-forme clearAllTables(): généralisation de clearAllTables(), ce qui la rend disponible sur toutes les plates-formes. Elle a également été convertie en fonction suspend. (I434ae, b/322846465)
• Migration destructive : ajout d'une valeur de paramètre par défaut à dropAllTables dans les API fallbackToDestructiveMigration. (Ica88b, b/438041176)

• Modifications apportées à l'API expérimentale :

  1. Déplacement de @ExperimentalRoomApi vers room-common pour permettre de marquer les API basées sur des annotations comme expérimentales.

  2. Ajout d'un RoomWarning expérimental pour supprimer l'exigence de @ConstructedBy dans une déclaration de base de données Room. Dans ce cas, DatabaseConstructor n'est pas généré, et une implémentation de fabrique doit être fournie via DatabaseBuilder. (If5443)

Correction de bugs

• Source de pagination : mise à jour de PagingSourceDaoReturnTypeConverter pour indiquer correctement que sa fonction de conversion est destinée aux requêtes READ. (I3b067, b/139872302)

Version 3.0.0-alpha01

11 mars 2026

Publication d'androidx.room3:room3-*:3.0.0-alpha01.

Room 3.0 (package androidx.room3) est une mise à jour majeure du package Room 2.x (androidx.room) qui se concentre sur Kotlin Multiplatform (KMP).

Les API d'annotation de base sont conservées, tout comme les composants principaux :

• Une classe abstraite qui étend androidx.room3.RoomDatabase et est annotée avec @Database est le point d'entrée du processeur d'annotations de Room.
• La déclaration de base de données comporte une ou plusieurs classes de données décrivant le schéma de la base de données et sont annotées avec @Entity.
• Les opérations de base de données sont définies dans des déclarations @Dao qui contiennent des fonctions de requête dont les instructions SQL sont définies via l'annotation @Query.
• Lors de l'exécution, l'implémentation de la base de données peut être obtenue via un RoomDatabase.Builder, qui est également utilisé pour configurer la base de données.

La majeure partie de la documentation du guide Enregistrer des données dans une base de données locale à l'aide de Room est toujours pertinente pour Room 3.0.

Voici les principales différences entre Room 2.x et Room 3.0 :

• Nouveau package, androidx.room3.
• Les API SupportSQLite ne sont plus compatibles, sauf si vous utilisez androidx.room3:room3-sqlite-wrapper.
• Toutes les opérations de base de données sont désormais basées sur les API Coroutine.
• Génération de code Kotlin uniquement.
• Le traitement des symboles Kotlin (KSP) est obligatoire.

Outre les modifications majeures, Room 3.0 apporte de nouvelles fonctionnalités par rapport à la version 2.x :

• Compatibilité avec JS et WasmJS
• Types renvoyés DAO personnalisés

Nouveau package

Pour éviter les problèmes de compatibilité avec les implémentations Room 2.x existantes et pour les bibliothèques avec des dépendances transitives à Room (par exemple, WorkManager), Room 3.0 réside dans un nouveau package, ce qui signifie qu'il possède également un nouveau groupe Maven et de nouveaux ID d'artefact. Par exemple, androidx.room:room-runtime est devenu androidx.room3:room3-runtime, et les classes telles que androidx.room.RoomDatabase se trouvent désormais dans androidx.room3.RoomDatabase.

Aucune API SupportSQLite

Room 3.0 est entièrement compatible avec les API SQLiteDriver et ne fait plus référence aux types SupportSQLite, tels que SupportSQLiteDatabase ni aux types Android, tels que Cursor. Il s'agit de la modification la plus importante entre Room 3.0 et 2.x, car les API RoomDatabase qui reflétaient SupportSQLiteDatabase, ainsi que l'API permettant d'obtenir un SupportSQLiteOpenHelper, ont été supprimées. Un SQLiteDriver est désormais obligatoire pour créer un RoomDatabase.

Par exemple, les API pour les opérations directes sur la base de données sont remplacées par des équivalents de pilote :

// 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 -> ... }
}

Les API de rappel qui avaient un SupportSQLiteDatabase comme argument ont également été remplacées par leur API équivalente qui a un SQLiteConnection comme argument. Il s'agit de fonctions de rappel de migration telles que Migration.onMigrate() et AutoMigrationSpec.onPostMigrate(), ainsi que de rappels de base de données tels que RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen(), etc.

Si Room était utilisé dans un projet KMP, la migration vers la version 3.0 est plus simple, car elle implique principalement la mise à jour des références d'importation. Sinon, la même stratégie de migration de Room dans Android uniquement vers KMP s'applique. Consultez le guide de migration KMP de Room.

Wrapper SupportSQLite

Room 3.x conserve le wrapper SupportSQLite créé dans la version 2.x pour faciliter les migrations et se trouve désormais dans un nouvel artefact androidx.room3:room3-sqlite-wrapper. L'API de compatibilité vous permet de convertir un RoomDatabase en SupportSQLiteDatabase. Les appels de roomDatabase.openHelper.writableDatabase peuvent être remplacés par roomDatabase.getSupportWrapper().

Kotlin et Coroutines en premier

Pour mieux faire évoluer la bibliothèque, Room 3.0 ne génère que du code Kotlin et n'est qu'un processeur de symboles Kotlin (KSP). Contrairement à Room 2.x, aucune génération de code Java ni aucune configuration du processeur d'annotations via KAPT ou JavaAP n'est plus possible dans Room 3.0. Notez que KSP est capable de traiter les sources Java et que le compilateur Room génère du code pour les bases de données, les entités ou les DAO dont les déclarations sources sont en Java. Il est recommandé d'avoir un projet multi-module où l'utilisation de Room est concentrée et où le plug-in Kotlin Gradle et KSP peuvent être appliqués sans affecter le reste de la base de code.

Room 3.0 nécessite également l'utilisation de Coroutines. Plus précisément, les fonctions DAO doivent être suspendues, sauf si elles renvoient un type réactif, tel qu'un Flow ou un type renvoyé DAO personnalisé. Les API Room permettant d'effectuer des opérations de base de données sont également des fonctions de suspension, telles que RoomDatabase.useReaderConnection et RoomDatabase.useWriterConnection.

Contrairement à Room 2.x, il n'est plus possible de configurer un RoomDatabase avec un Executor. Au lieu de cela, un CoroutineContext ainsi qu'un répartiteur peuvent être fournis via le compilateur de la base de données.

Les API InvalidationTracker de Room 3.0 sont basées sur Flow. InvalidationTracker.Observer est supprimé, ainsi que ses API pertinentes addObserver et removeObserver. Le mécanisme de réaction à l'opération de base de données passe par des flux de coroutines qui peuvent être créés via l'API createFlow() dans InvalidationTracker.

Exemples d'utilisation :

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

Assistance Web

La version 3.0 de Room ajoute JavaScript et WasmJs en tant que cibles KMP. Combiné à la sortie des SQLiteDriver interfaces (androidx.sqlite:sqlite) qui ciblent également JavaScript et WasmJs, et à un nouveau pilote WebWorkerSQLiteDriver situé dans le nouvel artefact androidx.sqlite:sqlite-web, il est possible d'utiliser Room dans un code commun qui cible toutes les principales plates-formes KMP.

En raison de la nature asynchrone des plates-formes Web, les API Room qui prenaient SQLiteStatement comme argument sont désormais des fonctions de suspension. Voici quelques exemples de ces fonctions : Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared(), etc. Dans les API de pilote, les API asynchrones sont courantes sur toutes les plates-formes, et les API synchrones sont courantes pour les cibles non Web. Par conséquent, un projet qui ne cible pas le Web peut continuer à utiliser les API synchrones (SQLiteDriver.open(), SQLiteConnection.prepare() et SQLiteStatement.step()) dans le code commun. En attendant, un projet qui ne cible que le Web doit utiliser les API asynchrones (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() et SQLiteStatement.stepAsync()).

Pour plus de commodité, le package androidx.sqlite a également ajouté des fonctions d'extension de suspension avec les noms synchrones des API mentionnées (avec l'ajout de SQLiteConnection.executeSQL). Ces API sont recommandées lorsque le projet cible à la fois les plates-formes Web et non Web, car les API sont des déclarations attendues / réelles qui appellent la bonne variante en fonction des plates-formes. Il s'agit des API utilisées par l'exécution de Room et qui permettent l'utilisation du pilote dans le code commun pour toutes les plates-formes compatibles.

Exemples d'utilisation :

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
}

Le WebWorkerSQLiteDriver est une implémentation d'un SQLiteDriver qui communique avec un Web Worker pour effectuer des opérations de base de données en dehors du thread principal et permet de stocker la base de données dans le système de fichiers privé d'origine (OPFS, Origin Private File System). Pour instancier le pilote un worker qui implémente un protocole de communication simple est requis. Le protocole est décrit dans le WebWorkerSQLiteDriver KDoc.

Actuellement, WebWorkerSQLiteDriver n'est pas fourni avec un worker par défaut qui implémente le protocole de communication, mais à titre d'exemple, la base de code androidx contient une implémentation de worker qui peut être utilisée dans votre projet. Il utilise le WASM de SQLite et stocke la base de données dans OPFS. L'exemple de worker est publié en tant que package NPM local et, grâce à la compatibilité de Kotlin avec les dépendances NPM, un petit module KMP peut être créé pour servir le worker.

Consultez le projet GitHub suivant qui illustre l'utilisation d'un Web Worker local pour Room.

Une fois qu'un worker est configuré dans le projet, la configuration de Room pour le Web est semblable à celle des autres plates-formes :

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

Une future version du pilote Web pourrait contenir un worker par défaut publié dans NPM, ce qui simplifierait la configuration Web.

Types renvoyés DAO personnalisés

Diverses intégrations de types renvoyés DAO, telles que celles pour RxJava et Paging, ont été transformées pour utiliser une nouvelle API dans Room 3.0 appelée convertisseurs de types renvoyés DAO. Une fonction de convertisseur de type renvoyé DAO (@DaoReturnTypeConverter) permet de transformer le résultat d'une fonction DAO en un type personnalisé défini par la fonction annotée. Ces fonctions permettent de participer au code généré par Room qui transforme les résultats de la requête en objets de données. Les classes qui contiennent des convertisseurs de types renvoyés DAO doivent être enregistrées via les @DaoReturnTypeConverters annotations dans les @Database ou @Dao déclarations.

Par exemple, pour qu'une requête DAO renvoie un PagingSource, la classe de convertisseur située dans androidx.room3:room3-paging doit maintenant être enregistrée :

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

Les intégrations existantes ont été déplacées vers des convertisseurs de types renvoyés DAO :

Comme les convertisseurs de types de colonne, les convertisseurs de types renvoyés DAO peuvent être définis par l'application. Par exemple, une application peut déclarer un @DaoReturnTypeConverter pour le type 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() }
    }
}

Le convertisseur ci-dessus permet ensuite aux fonctions de requête DAO de renvoyer Promise :

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

Une fonction @DaoReturnTypeConverter présente quelques exigences concernant le nombre de paramètres qu'elle doit comporter et ses types. Les paramètres possibles sont les suivants :

• db: RoomDatabase : (Facultatif) fournit un accès à l'instance RoomDatabase, ce qui peut être utile pour effectuer des opérations de base de données supplémentaires ou accéder au champ d'application de la coroutine.
• tableNames: Array<String> : (Facultatif) contient les tables consultées de la requête, ce qui est utile pour prendre en charge les types observables / réactifs lorsqu'ils sont combinés à l'API InvalidationTracker.createFlow() de Room.
• rawQuery: RoomRawQuery: (Facultatif) contient lors de l'exécution une instance de la requête, ce qui permet des transformations telles que la stratégie LIMIT / OFFSET implémentée par PagingSourceDaoReturnTypeConverter.
• executeAndConvert: suspend () -> T : (Obligatoire) fonction générée par Room qui exécute la requête et analyse son résultat dans des objets de données.

Pour en savoir plus sur les exigences concernant la création d'un convertisseur de type renvoyé DAO, consultez le KDoc sur l'@DaoReturnTypeConverter API.