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 mis en cache.

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

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 configurera 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 archivés dans le dépôt pour être utilisés pour la validation et les migrations automatiques.

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-alpha01

11 mars 2026

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

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

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

• Une classe abstraite qui étend androidx.room3.RoomDatabase et qui 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 base de données et est annotée 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.
• Au moment 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 plupart de la documentation du guide Enregistrer des données dans une base de données locale à l'aide de Room reste pertinente pour Room 3.0.

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

• Nouveau package, androidx.room3.
• Les API SupportSQLite ne sont plus prises en charge, 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 requis.

En plus des modifications destructives, Room 3.0 apporte de nouvelles fonctionnalités par rapport à la version 2.x :

• Compatibilité avec JS et WasmJS
• Types de retours de 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 nouvel ID de groupe Maven et des ID d'artefact. Par exemple, androidx.room:room-runtime est devenu androidx.room3:room3-runtime et les cours tels que androidx.room.RoomDatabase se trouvent désormais à l'adresse 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 de base de données directes 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 consiste principalement à mettre à jour les 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 Room KMP.

Wrapper SupportSQLite

Room 3.x conserve le wrapper SupportSQLite créé dans la version 2.x pour faciliter les migrations. Il 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 invocations de roomDatabase.openHelper.writableDatabase peuvent être remplacées par roomDatabase.getSupportWrapper().

Kotlin et les 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, la génération de code Java et la configuration du processeur d'annotation via KAPT ou JavaAP ne sont plus possibles dans Room 3.0. Notez que KSP est capable de traiter les sources Java et que le compilateur Room générera du code pour les bases de données, les entités ou les DAO dont les déclarations de source sont en Java. Il est recommandé d'avoir un projet multimodule 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. À la place, un CoroutineContext ainsi qu'un répartiteur peuvent être fournis via le générateur 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 associées addObserver et removeObserver. Le mécanisme permettant de réagir aux opérations de base de données passe par les 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 interfaces SQLiteDriver (androidx.sqlite:sqlite) qui ciblent également JavaScript et WasmJs, et d'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. Exemples de ces fonctions : Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() et autres. 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 revanche, 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 suspendues 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 "expect / actual" qui appelleront 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
}

WebWorkerSQLiteDriver est une implémentation de 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). Pour instancier le pilote, un nœud de calcul qui implémente un protocole de communication simple est requis. Ce protocole est décrit dans le KDoc WebWorkerSQLiteDriver.

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

Consultez le projet GitHub suivant qui montre comment utiliser un Web Worker local pour Room.

Une fois qu'un nœud de calcul est configuré dans le projet, la configuration de Room for the 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)"""))

Il est possible qu'une future version du pilote Web contienne un nœud de calcul par défaut publié dans NPM, ce qui simplifierait la configuration Web.

Types de retour DAO personnalisés

Diverses intégrations de types de retour 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 de retour DAO". Une fonction de conversion du type renvoyé par le 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 requête en objets de données. Les classes qui contiennent des convertisseurs de type de retour DAO doivent être enregistrées via les annotations @DaoReturnTypeConverters dans les déclarations @Database ou @Dao.

Par exemple, pour qu'une requête DAO renvoie un PagingSource, la classe de convertisseur située dans androidx.room3:room3-paging doit désormais ê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 les convertisseurs de type renvoyé DAO :

Comme les convertisseurs de type de colonne, les convertisseurs de type de retour de 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 doit respecter certaines exigences concernant le nombre de paramètres qu'elle doit comporter et leurs types. Voici les paramètres possibles :

• 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 auxquelles la requête a accédé. Il est utile pour prendre en charge les types observables / réactifs lorsqu'il est combiné à l'API InvalidationTracker.createFlow() de Room.
• rawQuery: RoomRawQuery : (facultatif) contient au moment 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écutera la requête et analysera son résultat en objets de données.

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