راه‌اندازی پایگاه داده Room برای KMP

کتابخانه پایداری Room یک لایه انتزاعی روی SQLite ارائه می‌دهد تا امکان دسترسی قوی‌تر به پایگاه داده را فراهم کند و درعین‌حال از قدرت کامل SQLite بهره ببرد. این صفحه بر استفاده از Room در پروژه‌های Kotlin Multiplatform (KMP) تمرکز دارد. برای اطلاعات بیشتر درباره استفاده از Room، به ذخیره داده‌ها در پایگاه داده محلی بااستفاده از Room یا نمونه‌های رسمی ما مراجعه کنید.

راه‌اندازی وابستگی‌ها

برای راه‌اندازی Room در پروژه KMP، وابستگی‌های مصنوعات را در فایل build.gradle.kts برای ماژول KMP خود اضافه کنید.

وابستگی‌ها را در فایل libs.versions.toml تعریف کنید:

[versions]
room3 = "3.1.0-alpha03"
sqlite = "2.7.1"
ksp = "<kotlinCompatibleKspVersion>"

[libraries]
androidx-sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "sqlite" }
androidx-room3-runtime = { module = "androidx.room3:room3-runtime", version.ref = "room3" }
androidx-room3-compiler = { module = "androidx.room3:room3-compiler", version.ref = "room3" }

# Optional SQLite Wrapper
androidx-room3-sqlite-wrapper = { module = "androidx.room3:room3-sqlite-wrapper", version.ref = "room3" }

[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
androidx-room3 = { id = "androidx.room3", version.ref = "room3" }

افزونه Room Gradle را برای پیکربندی طرح‌واره‌های Room و افزونه KSP اضافه کنید.

plugins {
  alias(libs.plugins.ksp)
  alias(libs.plugins.androidx.room3)
}

وابستگی زمان اجرای Room و کتابخانه SQLite بسته‌بندی‌شده را اضافه کنید:

commonMain.dependencies {
  implementation(libs.androidx.room3.runtime)
  implementation(libs.androidx.sqlite.bundled)
}

// Optional when using Room SQLite Wrapper
androidMain.dependencies {
  implementation(libs.androidx.room3.sqlite.wrapper)
}

وابستگی‌های KSP را به بلوک dependencies ریشه اضافه کنید. باید همه هدف‌هایی را که برنامه‌تان استفاده می‌کند اضافه کنید. برای اطلاعات بیشتر، به KSP با Kotlin Multiplatform مراجعه کنید.

dependencies {
    add("kspAndroid", libs.androidx.room3.compiler)
    add("kspIosSimulatorArm64", libs.androidx.room3.compiler)
    add("kspIosX64", libs.androidx.room3.compiler)
    add("kspIosArm64", libs.androidx.room3.compiler)
    // Add any other platform target you use in your project, for example kspDesktop
}

دایرکتوری طرح‌واره Room را تعریف کنید. برای اطلاعات بیشتر، به تنظیم مکان طرح‌واره بااستفاده از افزایه Room Gradle مراجعه کنید.

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

تعریف کردن کلاس‌های پایگاه داده

باید یک کلاس پایگاه داده با حاشیه‌نویسی @Database همراه با DAOها و موجودیت‌ها در مجموعه منبع مشترک ماژول KMP هم‌رسانی‌شده خود ایجاد کنید. قرار دادن این کلاس‌ها در منابع مشترک به آن‌ها اجازه می‌دهد در همه پلاتفرم‌های هدف هم‌رسانی شوند.

// 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("KotlinNoActualForExpect")
expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase> {
    override fun initialize(): AppDatabase
}

وقتی شیء expect را با میانای RoomDatabaseConstructor اعلام می‌کنید، کامپایلر Room پیاده‌سازی‌های actual را تولید می‌کند. «استودیو Android» ممکن است هشدار زیر را صادر کند که می‌توانید آن را با @Suppress("KotlinNoActualForExpect") متوقف کنید:

Expected object 'AppDatabaseConstructor' has no actual declaration in module`

سپس، یا یک میانای DAO جدید تعریف کنید یا میانای موجود را به commonMain منتقل کنید:

// shared/src/commonMain/kotlin/TodoDao.kt

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

نهادهای خود را به commonMain تعریف یا منتقل کنید:

// shared/src/commonMain/kotlin/TodoEntity.kt

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

ایجاد سازندگان پایگاه داده مختص پلاتفرم

باید یک سازنده پایگاه داده تعریف کنید تا Room را در هر پلاتفرم نمونه‌سازی کند. این تنها بخشی از میانای برنامه‌سازی کاربردی است که باید در مجموعه‌های منبع مختص پلاتفرم تعریف کنید، زیرا میاناهای برنامه‌سازی کاربردی سیستم فایل باهم تفاوت دارند.

Android

در Android، معمولاً مکان پایگاه داده را بااستفاده از Context.getDatabasePath API به‌دست می‌آورید. برای ایجاد نمونه پایگاه داده، Context و مسیر پایگاه داده را مشخص کنید.

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

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

iOS

برای ایجاد نمونه پایگاه داده در iOS، مسیر پایگاه داده را بااستفاده از NSFileManager ارائه دهید که معمولاً در NSDocumentDirectory قرار دارد.

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

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

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

JVM desktop

برای ایجاد نمونه پایگاه داده، مسیر پایگاه داده را بااستفاده از Java یا Kotlin APIs ارائه دهید.

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

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

نمونه‌سازی پایگاه داده

Once you obtain the RoomDatabase.Builder from one of the platform-specific constructors, you can configure the rest of the Room database in common code along with the actual database instantiation.

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

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

انتخاب درایور SQLite

تکه‌کد قبلی تابع سازنده setDriver را فراخوانی می‌کند تا مشخص کند پایگاه داده Room باید از کدام درایور SQLite استفاده کند. این درایورها براساس پلاتفرم هدف متفاوت هستند. تکه‌کدهای قبلی از BundledSQLiteDriver استفاده می‌کنند. این درایور توصیه‌شده است که شامل SQLite کامپایل‌شده از منبع است، که سازگارترین و به‌روزترین نسخه SQLite را در همه پلاتفرم‌ها ارائه می‌دهد.

اگر می‌خواهید از SQLite ارائه‌شده توسط سیستم‌عامل استفاده کنید، از میانای برنامه‌سازی کاربردی setDriver در مجموعه‌های منبع مختص پلاتفرم که درایور مختص پلاتفرم را مشخص می‌کنند استفاده کنید. برای شرح پیاده‌سازی‌های درایور دردسترس، پیاده‌سازی‌های درایور را ببینید. می‌توانید از یکی از موارد زیر استفاده کنید:

برای استفاده از NativeSQLiteDriver، باید گزینه پیونددهنده -lsqlite3 را ارائه دهید تا برنامه 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")
        }
    }
}

تنظیم زمینه هم‌روال

یک شیء RoomDatabase در Android می‌تواند به‌طور اختیاری با مجریان برنامه مشترک بااستفاده از RoomDatabase.Builder.setQueryExecutor برای انجام عملیات پایگاه داده پیکربندی شود.

چون اجراکننده‌ها با KMP سازگار نیستند، میانای برنامه‌سازی کاربردی setQueryExecutor Room در commonMain دردسترس نیست. درعوض، شیء RoomDatabase باید با CoroutineContext پیکربندی شود که می‌توانید آن را بااستفاده از RoomDatabase.Builder.setCoroutineContext تنظیم کنید. اگر زمینه‌ای تنظیم نکنید، شیء RoomDatabase به‌طور پیش‌فرض روی Dispatchers.IO تنظیم می‌شود.

کوچک‌سازی و مبهم‌سازی

اگر پروژه کوچک یا مبهم شده است، باید قانون ProGuard زیر را اضافه کنید تا Room بتواند پیاده‌سازی تولیدشده تعریف پایگاه داده را پیدا کند:

-keep class * extends androidx.room3.RoomDatabase { <init>(); }

انتقال به Kotlin چندپلاتفرمی

Room در ابتدا به‌عنوان کتابخانه Android توسعه داده شد و سپس با تمرکز بر سازگاری میانای برنامه‌سازی کاربردی به KMP منتقل شد. نسخه KMP از Room تا حدودی بین پلاتفرم‌ها و نسبت به نسخه ویژه Android متفاوت است. این تفاوت‌ها به‌صورت زیر فهرست و شرح داده شده‌اند.

انتقال از Support SQLite به SQLite Driver

هرگونه استفاده از SupportSQLiteDatabase و دیگر میاناهای برنامه‌سازی کاربردی در androidx.sqlite.db باید با میاناهای برنامه‌سازی کاربردی SQLite Driver بازسازی کد شود، زیرا میاناهای برنامه‌سازی کاربردی در androidx.sqlite.db فقط برای Android هستند (به بسته متفاوت از بسته KMP توجه کنید).

برای سازگاری با نسخه‌های قدیمی، و تا زمانی که RoomDatabase با SupportSQLiteOpenHelper.Factory پیکربندی شده باشد (برای مثال، هیچ SQLiteDriver تنظیم نشده باشد)، Room در «حالت سازگاری» رفتار می‌کند که در آن هر دو Support SQLite و SQLite Driver APIs طبق انتظار کار می‌کنند. این کار باعث فعال شدن انتقال‌های افزایشی می‌شود تا نیازی نباشد همه موارد استفاده از Support SQLite را در یک تغییر واحد به SQLite Driver تبدیل کنید.

استفاده از پوشاننده Room SQLite

ساخته androidx.room3:room3-sqlite-wrapper میاناهای برنامه‌سازی کاربردی‌ای ارائه می‌دهد که درطول انتقال، پلی بین SQLiteDriver و SupportSQLiteDatabase ایجاد می‌کند.

برای دریافت SupportSQLiteDatabase از RoomDatabase پیکربندی‌شده با SQLiteDriver، از تابع افزونه جدید RoomDatabase.getSupportWrapper استفاده کنید. این پوشش سازگاری به حفظ استفاده‌های موجود از SupportSQLiteDatabase کمک می‌کند، که اغلب از RoomDatabase.openHelper.writableDatabase دریافت می‌کنید، درحالی‌که SQLiteDriver را اتخاذ می‌کنید، به‌ویژه برای پایگاه‌های کد با استفاده‌های گسترده از SupportSQLite API که می‌خواهند از BundledSQLiteDriver استفاده کنند.

تبدیل زیرکلاس‌های انتقال

زیرکلاس‌های Migrations باید به همتایان درایور SQLite منتقل شوند:

Kotlin چندپلاتفرمی

زیرکلاس‌های انتقال

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

زیرکلاس‌های مشخصات انتقال خودکار

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

فقط Android

زیرکلاس‌های انتقال

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

زیرکلاس‌های مشخصات انتقال خودکار

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

تبدیل کردن پاسخ تماس پایگاه داده

فراخوانی‌های پایگاه داده باید به همتایان درایور SQLite منتقل شوند:

Kotlin چندپلاتفرمی

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

    override suspend fun onDestructiveMigration(connection: SQLiteConnection) {
        // ...
    }

    override suspend fun onOpen(connection: SQLiteConnection) {
        // ...
    }
}

فقط Android

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

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

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

تبدیل کردن توابع DAO @RawQuery

توابع حاشیه‌نویسی‌شده با @RawQuery که برای پلاتفرم‌های غیرAndroid کامپایل شده‌اند باید پارامتری از نوع RoomRawQuery را به‌جای SupportSQLiteQuery اعلام کنند.

Kotlin چندپلاتفرمی

تعریف پُرسمان خام

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

سپس می‌توان از RoomRawQuery برای ایجاد پُرسمان در زمان اجرا استفاده کرد:

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

    return getDao().getTodos(query)
}

فقط Android

تعریف پُرسمان خام

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

سپس می‌توان از SimpleSQLiteQuery برای ایجاد پُرسمان در زمان اجرا استفاده کرد:

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

تبدیل کردن توابع DAO مسدودکننده

Room از کتابخانه ناهمگام kotlinx.coroutines با ویژگی‌های غنی که Kotlin برای چندین پلاتفرم ارائه می‌دهد بهره می‌برد. برای عملکرد بهینه، توابع suspend برای DAOهای کامپایل‌شده در پروژه KMP اعمال می‌شوند، به‌جز DAOهای پیاده‌سازی‌شده در androidMain برای حفظ سازگاری با نسخه‌های قدیمی‌تر با پایگاه کد موجود. هنگام استفاده از Room برای KMP، همه توابع DAO که برای پلاتفرم‌های غیرAndroid کامپایل شده‌اند باید توابع suspend باشند.

Kotlin چندپلاتفرمی

درحال تعلیق پُرسمان‌ها

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

درحال تعلیق تراکنش‌ها

@Transaction
suspend fun transaction() {
    // ...
}

فقط Android

درحال مسدود کردن پُرسمان‌ها

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

مسدود کردن تراکنش‌ها

@Transaction
fun blockingTransaction() { … }

تبدیل انواع واکنشی به Flow

همه توابع DAO لازم نیست توابع تعلیق باشند. توابع DAO که انواع واکنشی مانند LiveData یا Flowable از RxJava را برمی‌گردانند نباید به توابع تعلیق تبدیل شوند. بااین‌حال، برخی‌از انواع، مثل LiveData، با KMP سازگار نیستند. توابع DAO با انواع بازگشت واکنشی باید به جریان‌های روال همگام منتقل شوند.

Kotlin چندپلاتفرمی

انواع واکنش Flows

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

فقط Android

انواع واکنشی مانند LiveData یا Flowable از RxJava

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

میاناهای برنامه‌سازی کاربردی تراکنش تبدیل

میاناهای برنامه‌سازی کاربردی تراکنش پایگاه داده برای Room KMP می‌توانند بین تراکنش‌های نوشتن (useWriterConnection) و خواندن (useReaderConnection) تمایز قائل شوند.

Kotlin چندپلاتفرمی

val database: RoomDatabase = getRoomDatabase(builder)
database.useWriterConnection { transactor ->
    transactor.immediateTransaction {
        // perform database operations in transaction.
    }
}

فقط Android

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

نوشتن تراکنش‌ها

از تراکنش‌های نوشتن استفاده کنید تا مطمئن شوید که چندین پُرسمان داده‌ها را به‌صورت اتمی می‌نویسند، تا خوانندگان بتوانند به‌طور مداوم به داده‌ها دسترسی داشته باشند. می‌توانید این کار را بااستفاده از useWriterConnection با هریک از سه نوع تراکنش انجام دهید:

  • immediateTransaction: در حالت ثبت پیش‌نویس (WAL) (پیش‌فرض)، این نوع تراکنش هنگام شروع قفل می‌شود، اما خوانندگان می‌توانند به خواندن ادامه دهند. این گزینه برای اکثر موارد ترجیح داده می‌شود.

  • ‫deferredTransaction: تراکنش تا اولین عبارت نوشتن، قفل را دریافت نخواهد کرد. وقتی مطمئن نیستید که آیا عملیات نوشتن در تراکنش لازم است یا نه، از این نوع تراکنش به‌عنوان بهینه‌سازی استفاده کنید. برای مثال، اگر تراکنشی را برای حذف آهنگ‌ها از فهرست پخشی شروع کنید که فقط نام فهرست پخش را دارد و فهرست پخش وجود ندارد، هیچ عملیات نوشتنی (حذف) لازم نیست.

  • exclusiveTransaction: این حالت دقیقاً مانند immediateTransaction در حالت WAL عمل می‌کند. در حالت‌های دیگر ثبت وقایع، این ویژگی از خواندن پایگاه داده توسط دیگر اتصال‌های پایگاه داده درحین انجام تراکنش جلوگیری می‌کند.

خواندن تراکنش‌ها

از تراکنش‌های خواندن برای خواندن مداوم از پایگاه داده به‌دفعات استفاده کنید. برای مثال، وقتی دو یا چند پُرسمان جداگانه دارید و از عبارت JOIN استفاده نمی‌کنید. فقط تراکنش‌های معوقه در اتصالات کارت‌خوان مجاز است. تلاش برای شروع تراکنش فوری یا انحصاری در اتصال خواننده، استثنا ایجاد می‌کند، زیرا این تراکنش‌ها به‌عنوان عملیات «نوشتن» درنظر گرفته می‌شوند.

val database: RoomDatabase = getRoomDatabase(builder)
database.useReaderConnection { transactor ->
    transactor.deferredTransaction {
        // perform database operations in transaction.
    }
}

در Kotlin چندپلاتفرمی دردسترس نیست

برخی‌از میاناهای برنامه‌سازی کاربردی که برای Android دردسترس بودند در Kotlin Multiplatform دردسترس نیستند.

پاسخ تماس پُرسمان

میاناهای برنامه‌سازی کاربردی زیر برای پیکربندی بازخوانی‌های پُرسمان به‌طور مشترک دردسترس نیستند و بنابراین در پلاتفرم‌هایی غیراز Android دردسترس نیستند.

  • RoomDatabase.Builder.setQueryCallback
  • RoomDatabase.QueryCallback

درحال بستن خودکار پایگاه داده

میانای برنامه‌سازی کاربردی برای فعال کردن بستن خودکار پس‌از اتمام مهلت، RoomDatabase.Builder.setAutoCloseTimeout، فقط در Android دردسترس است.

پایگاه داده ازپیش بسته‌بندی‌شده

میاناهای برنامه‌سازی کاربردی زیر برای ایجاد RoomDatabase بااستفاده از پایگاه داده موجود (پایگاه داده ازپیش بسته‌بندی‌شده) به‌طور معمول دردسترس نیستند و بنابراین در پلاتفرم‌هایی غیراز Android دردسترس نیستند:

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

ابطال چندنمونه‌ای

میانای برنامه‌سازی کاربردی برای فعال کردن باطل‌سازی چندنمونه‌ای، RoomDatabase.Builder.enableMultiInstanceInvalidation، فقط در Android دردسترس است و در پلاتفرم‌های رایج یا دیگر دردسترس نیست.