Configurer la base de données Room pour KMP

Pour assurer la rétrocompatibilité, et tant que RoomDatabase est configuré avec un SupportSQLiteOpenHelper.Factory (par exemple, aucun SQLiteDriver n'est défini), Room se comporte en "mode de compatibilité" où les API Support SQLite et SQLite Driver fonctionnent comme prévu. Cela permet des migrations incrémentielles afin que vous n'ayez pas besoin de convertir toutes vos utilisations de Support SQLite en pilote SQLite en une seule modification.

Utiliser le wrapper SQLite de Room

L'artefact androidx.room3:room3-sqlite-wrapper fournit des API pour établir un pont entre SQLiteDriver et SupportSQLiteDatabase lors de la migration.

Pour obtenir un SupportSQLiteDatabase à partir d'un RoomDatabase configuré avec un SQLiteDriver, utilisez la nouvelle fonction d'extension RoomDatabase.getSupportWrapper. Ce wrapper de compatibilité permet de conserver les utilisations existantes de SupportSQLiteDatabase, que vous obtenez souvent à partir de RoomDatabase.openHelper.writableDatabase, tout en adoptant SQLiteDriver, en particulier pour les bases de code avec des utilisations étendues de l'API SupportSQLite qui souhaitent utiliser BundledSQLiteDriver.

Convertir les sous-classes de migration

Les sous-classes de migration doivent être migrées vers les homologues du pilote SQLite :

object Migration_1_2 : Migration(1, 2) {
  override fun migrate(connection: SQLiteConnection) {
    // …
  }
}

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
  override fun onPostMigrate(connection: SQLiteConnection) {
    // …
  }
}

object Migration_1_2 : Migration(1, 2) {
  override fun migrate(db: SupportSQLiteDatabase) {
    // …
  }
}

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
  override fun onPostMigrate(db: SupportSQLiteDatabase) {
    // …
  }
}

Convertir le rappel de base de données

Les rappels de base de données doivent être migrés vers les homologues du pilote SQLite :

object MyRoomCallback : RoomDatabase.Callback() {
  override fun onCreate(connection: SQLiteConnection) {
    // …
  }

  override fun onDestructiveMigration(connection: SQLiteConnection) {
    // …
  }

  override fun onOpen(connection: SQLiteConnection) {
    // …
  }
}

object MyRoomCallback : RoomDatabase.Callback() {
  override fun onCreate(db: SupportSQLiteDatabase) {
    // …
  }

  override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
    // …
  }

  override fun onOpen(db: SupportSQLiteDatabase) {
    // …
  }
}

Convertir les fonctions DAO @RawQuery

Les fonctions annotées avec @RawQuery qui sont compilées pour des plates-formes non Android devront déclarer un paramètre de type RoomRawQuery au lieu de SupportSQLiteQuery.

@Dao
interface TodoDao {
  @RawQuery
  suspend fun getTodos(query: RoomRawQuery): List<TodoEntity>
}

suspend fun AppDatabase.getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
    val query = RoomRawQuery(
        sql = "SELECT * FROM TodoEntity WHERE title = ?",
        onBindStatement = {
            it.bindText(1, title.lowercase())
        }
    )

    return todoDao().getTodos(query)
}

@Dao
interface TodoDao {
  @RawQuery
  suspend fun getTodos(query: SupportSQLiteQuery): List<TodoEntity>
}

suspend fun AndroidOnlyDao.getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
  val query = SimpleSQLiteQuery(
      query = "SELECT * FROM TodoEntity WHERE title = ?",
      bindArgs = arrayOf(title.lowercase())
  )
  return getTodos(query)
}

Convertir les fonctions DAO bloquantes

Room bénéficie de la bibliothèque asynchrone riche en fonctionnalités kotlinx.coroutines que Kotlin propose pour plusieurs plates-formes. Pour une fonctionnalité optimale, les fonctions suspend sont appliquées aux DAO compilés dans un projet KMP, à l'exception des DAO implémentés dans androidMain pour maintenir la rétrocompatibilité avec la base de code existante. Lorsque vous utilisez Room pour KMP, toutes les fonctions DAO compilées pour des plates-formes non Android doivent être des fonctions suspend.

@Query("SELECT * FROM Todo")
suspend fun getAllTodos(): List<Todo>

@Transaction
suspend fun transaction() { … }

@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>

@Transaction
fun blockingTransaction() { … }

Convertir les types réactifs en flux

Toutes les fonctions DAO n'ont pas besoin d'être des fonctions de suspension. Les fonctions DAO qui renvoient des types réactifs tels que LiveData ou Flowable de RxJava ne doivent pas être converties en fonctions de suspension. Toutefois, certains types, tels que LiveData, ne sont pas compatibles avec KMP. Les fonctions DAO avec des types de retour réactifs doivent être migrées vers des flux de coroutine.

@Query("SELECT * FROM Todo")
fun getTodosFlow(): Flow<List<Todo>>

@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>

Convertir les API de transaction

Les API de transaction de base de données pour Room KMP peuvent faire la distinction entre les transactions d'écriture (useWriterConnection) et de lecture (useReaderConnection).

val database: RoomDatabase = …
database.useWriterConnection { transactor ->
  transactor.immediateTransaction {
    // perform database operations in transaction
  }
}

val database: RoomDatabase = …
database.withTransaction {
  // perform database operations in transaction
}

Transactions d'écriture

Utilisez des transactions d'écriture pour vous assurer que plusieurs requêtes écrivent des données de manière atomique, afin que les lecteurs puissent accéder aux données de manière cohérente. Pour ce faire, utilisez useWriterConnection avec l'un des trois types de transaction :

• immediateTransaction : en mode WAL (Write-Ahead Logging) (par défaut), ce type de transaction acquiert un verrou au démarrage, mais les lecteurs peuvent continuer à lire. Il s'agit du choix préféré dans la plupart des cas.

• deferredTransaction: la transaction n'acquiert pas de verrou tant que la première instruction d'écriture n'est pas exécutée. Utilisez ce type de transaction comme optimisation lorsque vous n'êtes pas sûr qu'une opération d'écriture sera nécessaire dans la transaction. Par exemple, si vous démarrez une transaction pour supprimer des titres d'une playlist en indiquant uniquement le nom de la playlist et que la playlist n'existe pas, aucune opération d'écriture (suppression) n'est nécessaire.

• exclusiveTransaction: ce mode se comporte de la même manière que immediateTransaction en mode WAL. Dans d'autres modes de journalisation, il empêche d'autres connexions à la base de données de lire la base de données pendant la transaction.

Transactions de lecture

Utilisez des transactions de lecture pour lire plusieurs fois de manière cohérente à partir de la base de données. Par exemple, lorsque vous avez deux requêtes distinctes ou plus et que vous n'utilisez pas de clause JOIN. Seules les transactions différées sont autorisées dans les connexions de lecteur. Toute tentative de démarrage d'une transaction immédiate ou exclusive dans une connexion de lecteur générera une exception, car il s'agit d'opérations d'écriture.

val database: RoomDatabase = …
database.useReaderConnection { transactor ->
  transactor.deferredTransaction {
      // perform database operations in transaction
  }
}

Non disponible dans Kotlin Multiplatform

Certaines API disponibles pour Android ne sont pas disponibles dans Kotlin Multiplatform.

Rappel de requête

Les API suivantes pour configurer les rappels de requête ne sont pas disponibles en commun et ne sont donc pas disponibles sur les plates-formes autres qu'Android.

• RoomDatabase.Builder.setQueryCallback
• RoomDatabase.QueryCallback

Nous prévoyons d'ajouter la prise en charge des rappels de requête dans une future version de Room.

L'API permettant de configurer un RoomDatabase avec un rappel de requête RoomDatabase.Builder.setQueryCallback ainsi que l'interface de rappel RoomDatabase.QueryCallback ne sont pas disponibles en commun et ne sont donc pas disponibles sur les plates-formes autres qu'Android.

Fermeture automatique de la base de données

L'API permettant d'activer la fermeture automatique après un délai d'inactivité, RoomDatabase.Builder.setAutoCloseTimeout, n'est disponible que sur Android et n'est pas disponible sur d'autres plates-formes.

Base de données pré-empaquetée

Les API suivantes permettant de créer un RoomDatabase à l'aide d'une base de données existante (c'est-à-dire une base de données pré-empaquetée) ne sont pas disponibles en commun et ne sont donc pas disponibles sur les plates-formes autres qu'Android. Voici la liste de ces API :

• RoomDatabase.Builder.createFromAsset
• RoomDatabase.Builder.createFromFile
• RoomDatabase.Builder.createFromInputStream
• RoomDatabase.PrepackagedDatabaseCallback

Nous prévoyons d'ajouter la prise en charge des bases de données pré-empaquetées dans une future version de Room.

Invalidation multi-instance

L'API permettant d'activer l'invalidation multi-instance, RoomDatabase.Builder.enableMultiInstanceInvalidation, n'est disponible que sur Android et n'est pas disponible en commun ni sur d'autres plates-formes.