このページは Cloud Translation API によって翻訳されました。

Room（Kotlin マルチプラットフォーム）

Room 永続ライブラリは、SQLite に抽象化レイヤを提供することで、では、SQLite を最大限に活用しながら、より堅牢なデータベースアクセスを実現できます。このこのページでは、Kotlin マルチプラットフォーム（KMP）プロジェクトで Room を使用する方法に焦点を当てます。詳細 Room の使用について詳しくは、Room を使用してローカルデータベースにデータを保存するをご覧ください。または公式サンプルをご覧ください。

依存関係をセットアップする

KMP をサポートしている Room の現在のバージョンは次のとおりです。 2.7.0-alpha01 以降

KMP プロジェクトで Room を設定するには、モジュールの build.gradle.kts ファイルに追加します。

androidx.room:room-gradle-plugin - Room スキーマを構成するための Gradle プラグイン
androidx.room:room-compiler - コードを生成する KSP プロセッサ
androidx.room:room-runtime - ライブラリのランタイム部分
androidx.sqlite:sqlite-bundled - （省略可）バンドルされた SQLite ライブラリ

また、Room の SQLite ドライバを構成する必要があります。これらの要因はターゲットプラットフォームに応じて自動的に作成されます詳しくは、ドライバの実装を参照してください。

その他の設定情報については、以下をご覧ください。

で確認できます。

データベースクラスの定義

DAO とともに @Database アノテーション付きのデータベースクラスを作成する必要があります共有 KMP モジュールの共通ソースセット内のエンティティを確認できます。配置共通ソース内でこれらのクラスを使用すると、ターゲット説明します。

インターフェースを使用して expect オブジェクトを宣言する場合 RoomDatabaseConstructor: Room コンパイラが actual を生成しますあります。Android Studio が警告を発することがある "Expected object 'AppDatabaseConstructor' has no actual declaration in module"、@Suppress("NO_ACTUAL_FOR_EXPECT") を使用して警告を抑制できます。

// shared/src/commonMain/kotlin/Database.kt

@Database(entities = [TodoEntity::class], version = 1)
@ConstructedBy(AppDatabaseConstructor::class)
abstract class AppDatabase : RoomDatabase() {
  abstract fun getDao(): TodoDao
}

// The Room compiler generates the `actual` implementations.
@Suppress("NO_ACTUAL_FOR_EXPECT")
expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase> {
    override fun initialize(): AppDatabase
}

@Dao
interface TodoDao {
  @Insert
  suspend fun insert(item: TodoEntity)

  @Query("SELECT count(*) FROM TodoEntity")
  suspend fun count(): Int

  @Query("SELECT * FROM TodoEntity")
  fun getAllAsFlow(): Flow<List<TodoEntity>>
}

@Entity
data class TodoEntity(
  @PrimaryKey(autoGenerate = true) val id: Long = 0,
  val title: String,
  val content: String
)

なお、実際の宣言 / 期待される宣言を必要に応じて使用できます。を使用してプラットフォーム固有の Room 実装を作成します。たとえば、共通のコードで定義されるプラットフォーム固有の DAO。expect を使用してプラットフォーム固有のクエリを追加して actual 定義を指定するソースセットです

データベースビルダーの作成

各プラットフォームで Room をインスタンス化するために、データベースビルダーを定義する必要があります。このプラットフォーム固有のソースに配置する必要がある API の唯一の部分異なるためです。たとえば Android ではデータベースの場所は通常、 Context.getDatabasePath() API を使用します。iOS の場合、データベースのロケーションは NSFileManager を使用して取得できます。

Android

データベースインスタンスを作成するには、データベースとともに [Context] を指定します。あります。

// shared/src/androidMain/kotlin/Database.kt

fun getDatabaseBuilder(ctx: Context): RoomDatabase.Builder<AppDatabase> {
  val appContext = ctx.applicationContext
  val dbFile = appContext.getDatabasePath("my_room.db")
  return Room.databaseBuilder<AppDatabase>(
    context = appContext,
    name = dbFile.absolutePath
  )
}

iOS

データベースインスタンスを作成するには、 NSFileManager（通常は NSDocumentDirectory にあります）。

// shared/src/iosMain/kotlin/Database.kt

fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> {
    val dbFilePath = documentDirectory() + "/my_room.db"
    return Room.databaseBuilder<AppDatabase>(
        name = dbFilePath,
    )
}

private fun documentDirectory(): String {
  val documentDirectory = NSFileManager.defaultManager.URLForDirectory(
    directory = NSDocumentDirectory,
    inDomain = NSUserDomainMask,
    appropriateForURL = null,
    create = false,
    error = null,
  )
  return requireNotNull(documentDirectory?.path)
}

JVM（デスクトップ）

データベースインスタンスを作成するには、Java または Kotlin を使用してデータベースパスを指定します API

// shared/src/jvmMain/kotlin/Database.kt

fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> {
    val dbFile = File(System.getProperty("java.io.tmpdir"), "my_room.db")
    return Room.databaseBuilder<AppDatabase>(
        name = dbFile.absolutePath,
    )
}

データベースのインスタンス化

プラットフォーム固有の API から RoomDatabase.Builder を取得したら、 Room データベースの残りの部分は共通のコードで構成できます。実際のデータベースのインスタンス化も一緒に行います

// shared/src/commonMain/kotlin/Database.kt

fun getRoomDatabase(
    builder: RoomDatabase.Builder<AppDatabase>
): AppDatabase {
  return builder
      .addMigrations(MIGRATIONS)
      .fallbackToDestructiveMigrationOnDowngrade()
      .setDriver(BundledSQLiteDriver())
      .setQueryCoroutineContext(Dispatchers.IO)
      .build()
}

SQLiteDriver の選択

上記のコードスニペットでは BundledSQLiteDriver を使用しています。これが推奨ドライバには、ソースからコンパイルされた SQLite が含まれます。すべてのプラットフォームで最も整合性の高い最新バージョンの SQLite を提供すること。もし OS 提供の SQLite を使用する場合は、プラットフォーム固有の setDriver API を使用します。プラットフォーム固有のドライバを指定するソースセットです。Android の場合は、次のコマンドを使用します。 AndroidSQLiteDriver。iOS の場合は NativeSQLiteDriver を使用できます。宛先 NativeSQLiteDriver を使用するには、リンカーオプションを提供して、iOS アプリがアプリをシステム SQLite と動的にリンクします。

// shared/build.gradle.kts

kotlin {
    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "TodoApp"
            isStatic = true
            // Required when using NativeSQLiteDriver
            linkerOpts.add("-lsqlite3")
        }
    }
}

相違点

Room はもともと Android ライブラリとして開発され、その後 API の互換性に重点を置いた KMP。Room の KMP バージョンは多少異なるプラットフォーム間の違いや Android 固有のバージョンからの違いですこれらの違いは、以下で説明します。

ブロック DAO 関数

Room for KMP を使用する場合、Android 以外のプラットフォーム用にコンパイルされたすべての DAO 関数がリアクティブの戻り値の型を除き、suspend 関数にする必要があります。 Flow として。

// shared/src/commonMain/kotlin/MultiplatformDao.kt

@Dao
interface MultiplatformDao {
  // ERROR: Blocking function not valid for non-Android targets
  @Query("SELECT * FROM Entity")
  fun blockingQuery(): List<Entity>

  // OK
  @Query("SELECT * FROM Entity")
  suspend fun query(): List<Entity>

  // OK
  @Query("SELECT * FROM Entity")
  fun queryFlow(): Flow<List<Entity>>

  // ERROR: Blocking function not valid for non-Android targets
  @Transaction
  fun blockingTransaction() { // … }

  // OK
  @Transaction
  suspend fun transaction() { // … }
}

豊富な機能を備えた非同期 kotlinx.coroutines ライブラリが Room で利用できる複数のプラットフォームに利用できます最適な機能を得るには、suspend 関数は、KMP プロジェクトでコンパイルされた DAO に適用されます。ただし、例外として既存の DAO との下位互換性を維持するための Android 固有の DAO 学びました。

KMP との機能の違い

このセクションでは、KMP と Android プラットフォームの機能の違いについて説明します。できません。

@RawQuery DAO 関数

Android 以外のプラットフォーム用にコンパイルされた、@RawQuery アノテーション付きの関数代わりに RoomRawQuery 型のパラメータを宣言し、 SupportSQLiteQuery。

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

RoomRawQuery を使用すると、実行時にクエリを作成できます。

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

クエリコールバック

クエリコールバックを構成するための次の API は、一般的には使用できない Android 以外のプラットフォームでは使用できません。

RoomDatabase.Builder.setQueryCallback
RoomDatabase.QueryCallback

Room の今後のバージョンで、クエリコールバックのサポートを追加する予定です。

クエリコールバックを使用して RoomDatabase を構成する API RoomDatabase.Builder.setQueryCallback とコールバックインターフェース RoomDatabase.QueryCallback は共通で使用できないため、使用できません Android 以外のプラットフォームでも利用できます

データベースの自動終了

タイムアウト後の自動終了を有効にする API RoomDatabase.Builder.setAutoCloseTimeout は、Android でのみご利用いただけます。他のプラットフォームでは利用できません。

パッケージ化前のデータベース

次の API を使用して、RoomDatabase既存のデータベース（事前パッケージ化済みデータベースなど）は、一般的には利用できないため、 Android 以外のプラットフォームで利用できますこれらの API は次のとおりです。

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

次のバージョンで、事前パッケージ化済みデータベースのサポートを追加する予定です。会議室。

マルチインスタンスの無効化

複数インスタンスの無効化を有効にする API RoomDatabase.Builder.enableMultiInstanceInvalidation は以下でのみご利用いただけます: 一般的なプラットフォームや他のプラットフォームでは利用できません。