SQLite에서 Room으로 이전

Room 지속성 라이브러리를 사용하면 SQLite API를 직접 사용하는 것보다 여러 가지 이점이 있습니다.

• SQL 쿼리의 컴파일 시간 확인
• 반복적이고 오류가 발생하기 쉬운 상용구 코드를 최소화하는 편의 주석
• 간소화된 데이터베이스 이전 경로

앱에 Room이 아닌 SQLite 구현이 있다면 이 페이지를 참고하여 Room으로 이전하는 방법을 알아보세요. 앱에서 사용하는 첫 번째 SQLite 구현이 Room이라면 기본 사용법은 Room을 사용하여 로컬 데이터베이스에 데이터 저장을 참고하세요.

이전 단계

다음 단계를 따라 SQLite 구현을 Room으로 이전하세요. SQLite 구현에서 대규모 데이터베이스나 복잡한 쿼리를 사용한다면 점진적으로 Room으로 이전하는 것이 좋습니다. 증분 이전 전략에 관한 자세한 내용은 증분 이전을 참고하세요.

종속 항목 업데이트

앱에서 Room을 사용하려면 적절한 종속 항목을 앱의 build.gradle 파일에 포함해야 합니다. Room 종속 항목에 관한 자세한 내용은 설정을 참고하세요.

모델 클래스를 데이터 항목으로 업데이트

Room은 데이터 항목을 사용하여 데이터베이스의 테이블을 나타냅니다. 각 항목 클래스는 테이블을 나타내며 테이블의 열을 나타내는 속성이 있습니다. 다음 단계를 따라 기존 모델 클래스를 Room 항목으로 업데이트하세요.

1. 클래스 선언에 @Entity 주석을 달아 Room 항목임을 표시합니다. 선택적으로 tableName 속성을 사용하여 결과 테이블의 이름이 클래스 이름과 달라야 함을 나타낼 수 있습니다.
2. 기본 키 속성에 @PrimaryKey 주석을 답니다.
3. 결과 테이블의 열 중 하나라도 이름이 상응하는 속성의 이름과 달라야 한다면 해당 속성에 @ColumnInfo 주석을 달고 name 속성을 올바른 열 이름으로 설정합니다.
4. 데이터베이스에 유지하지 않으려는 속성이 클래스에 있다면 해당 속성에 @Ignore 주석을 달아 Room 이 상응하는 테이블에 관련 열을 만들지 않도록 표시해 줍니다.
5. 클래스에 생성자가 2개 이상 있으면 나머지 생성자에 모두 @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 만들기

Room은 데이터 액세스 객체 (DAO)를 사용하여 데이터베이스에 액세스하는 함수를 정의합니다. Room 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의 데이터베이스 이전 경로에 관한 자세한 내용은 데이터베이스 이전을 참고하세요.

데이터베이스 인스턴스화 업데이트

데이터베이스 클래스와 이전 경로를 정의한 후 Room.databaseBuilder를 사용하여 이전 경로가 적용된 데이터베이스 인스턴스를 만들 수 있습니다.

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

구현 테스트

다음과 같이 새 Room 구현을 테스트해야 합니다.

• 이전 테스트의 안내에 따라 데이터베이스 이전을 테스트합니다.
• 데이터베이스 테스트의 안내에 따라 DAO 함수를 테스트합니다.

증분 이전

복잡한 대규모 데이터베이스를 사용하는 앱은 한 번에 Room으로 이전하지 못할 수도 있습니다. 대신 첫 단계에서 데이터 항목과 Room 데이터베이스를 선택적으로 구현하고 나중에 쿼리 함수를 DAO로 이전할 수 있습니다.

증분 이전을 구현하려면 androidx.room3:room3-sqlite-wrapper 아티팩트의 roomDatabase.getSupportWrapper 확장 함수를 사용하여 SupportSQLiteDatabase 호환성 래퍼를 가져옵니다. 이 래퍼를 사용하면 Android SQLite API를 사용하여 Room 관리 데이터베이스에서 직접 Android 스타일 SQL 쿼리를 실행할 수 있습니다.

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