انتقال از SQLite به Room

کتابخانه ماندگاری «اتاق» مزایای متعددی نسبت‌به استفاده مستقیم از واسط‌های برنامه‌سازی کاربردی SQLite دارد:

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

اگر برنامه شما پیاده‌سازی غیر-Room SQLite دارد، این صفحه را بخوانید تا با نحوه انتقال به Room آشنا شوید. اگر Room اولین پیاده‌سازی SQLite در برنامه شما است، برای استفاده‌های اولیه، ذخیره داده‌ها در پایگاه داده محلی بااستفاده از Room را ببینید.

مراحل انتقال

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

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

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

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

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

1. اعلان کلاس را با @Entity نشان‌گذاری کنید تا نشان دهید که این یک نهاد «اتاق» است. می‌توانید به‌صورت اختیاری از دارایی 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

ایجاد سازمان‌های خودگردان غیرمتمرکز

‫Room از اشیای دسترسی به داده (DAOs) برای تعریف توابعی که به پایگاه داده دسترسی دارند استفاده می‌کند. برای جایگزین کردن تابع‌های پُرسمان موجود با «اشیا دسترسی به داده‌ها»، از راهنمایی‌های دسترسی به داده‌ها بااستفاده از «اشیا دسترسی به داده‌های Room» پیروی کنید.

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

پیاده‌سازی‌های «اتاق» از کلاس پایگاه داده برای مدیریت نمونه پایگاه داده استفاده می‌کنند. کلاس پایگاه داده شما باید RoomDatabase را گسترش دهد و به همه نهادها و «اشیا دسترسی به داده» (DAOs) که تعریف کرده‌اید ارجاع دهد.

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

@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، به انتقال پایگاه داده مراجعه کنید.

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

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

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

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

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

• برای آزمایش انتقال پایگاه داده، راهنمایی‌های انتقال‌های آزمایشی را دنبال کنید.
• برای آزمایش کردن تابع‌های DAO، راهنمایی‌های آزمایش کردن پایگاه داده را دنبال کنید.

انتقال افزایشی

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

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

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