از SQLite به Room مهاجرت کنید

کتابخانه‌ی Room persistence مزایای متعددی نسبت به استفاده‌ی مستقیم از APIهای SQLite ارائه می‌دهد:

• تأیید زمان کامپایل کوئری‌های SQL
• حاشیه‌نویسی‌های راحت که کدهای تکراری و مستعد خطا را به حداقل می‌رسانند
• مسیرهای مهاجرت پایگاه داده ساده شده

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

مراحل مهاجرت

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

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

برای استفاده از Room در برنامه خود، باید وابستگی‌های مناسب را در فایل build.gradle برنامه خود قرار دهید. برای اطلاعات بیشتر در مورد وابستگی‌های Room، به بخش تنظیمات مراجعه کنید.

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

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

1. اعلان کلاس را با @Entity حاشیه‌نویسی کنید تا مشخص شود که یک موجودیت Room است. می‌توانید به صورت اختیاری از ویژگی tableName برای مشخص کردن اینکه جدول حاصل باید نامی متفاوت از نام کلاس داشته باشد، استفاده کنید.
2. ویژگی کلید اصلی را با @PrimaryKey حاشیه‌نویسی کنید.
3. اگر هر یک از ستون‌های جدول حاصل باید نامی متفاوت از نام ویژگی مربوطه داشته باشد، آن ویژگی را با @ColumnInfo حاشیه‌نویسی کنید و ویژگی name را روی نام ستون صحیح تنظیم کنید.
4. اگر کلاس دارای ویژگی‌هایی است که نمی‌خواهید در پایگاه داده باقی بمانند، آن ویژگی‌ها را با @Ignore حاشیه‌نویسی کنید تا نشان دهید که Room نباید ستون‌هایی برای آنها در جدول مربوطه ایجاد کند.
5. اگر کلاس بیش از یک سازنده دارد، با حاشیه‌نویسی تمام سازنده‌های دیگر با @Ignore ، مشخص کنید که Room باید از کدام سازنده استفاده کند.

@Entity(tableName = "users")
data class User(
    @PrimaryKey @ColumnInfo(name = "userid") val id: String,
    @ColumnInfo(name = "username") val userName: String?,
    @ColumnInfo(name = "last_update") val date: Date?,
)
SqliteRoomMigrationSnippets.kt

ایجاد DAOها

روم از اشیاء دسترسی به داده (DAO) برای تعریف توابعی که به پایگاه داده دسترسی دارند استفاده می‌کند. برای جایگزینی توابع پرس و جوی موجود خود با DAOها، راهنمای « دسترسی به داده‌ها با استفاده از DAOهای روم» را دنبال کنید.

ایجاد کلاس پایگاه داده

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

@Database(entities = [User::class], version = 2)
@ColumnTypeConverters(DateConverter::class)
abstract class UsersDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}
SqliteRoomMigrationSnippets.kt

تعریف مسیر مهاجرت

از آنجا که شماره نسخه پایگاه داده در حال تغییر است، شما باید یک شیء Migration برای حفظ داده‌های پایگاه داده موجود تعریف کنید. اگر طرحواره پایگاه داده تغییر نکند، این مهاجرت می‌تواند خالی باشد.

val MIGRATION_1_2 = object : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // Empty implementation, because the schema isn't changing.
    }
}
SqliteRoomMigrationSnippets.kt

برای اطلاعات بیشتر در مورد مسیرهای مهاجرت پایگاه داده در Room، به Migrate your database مراجعه کنید.

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

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

val db =
    Room.databaseBuilder<UsersDatabase>(applicationContext, "database-name")
        .addMigrations(MIGRATION_1_2)
        .build()
SqliteRoomMigrationSnippets.kt

پیاده‌سازی خود را آزمایش کنید

حتماً پیاده‌سازی جدید Room خود را آزمایش کنید:

• برای آزمایش مهاجرت پایگاه داده خود، راهنمایی‌های موجود در بخش «آزمایش مهاجرت‌ها» را دنبال کنید.
• برای آزمایش توابع DAO خود، از راهنمایی‌های موجود در بخش «آزمایش پایگاه داده» پیروی کنید.

مهاجرت افزایشی

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

برای پیاده‌سازی یک مهاجرت افزایشی، یک پوشش سازگاری SupportSQLiteDatabase را با استفاده از تابع الحاقی roomDatabase.getSupportWrapper از مصنوع androidx.room3:room3-sqlite-wrapper دریافت کنید. این پوشش به شما امکان می‌دهد تا با استفاده از APIهای Android SQLite، کوئری‌های SQL به سبک اندروید را مستقیماً روی پایگاه داده مدیریت‌شده توسط Room اجرا کنید:

// Get SupportSQLiteDatabase wrapper
val legacyDb = roomDatabase.getSupportWrapper()
legacyDb.execSQL("INSERT INTO users ...")
SqliteRoomMigrationSnippets.kt