Room 3.0

Room 지속성 라이브러리는 SQLite에 추상화 레이어를 제공하여 SQLite를 완벽히 활용하면서 더 견고한 데이터베이스 액세스를 가능하게 합니다.

최근 업데이트	안정화 버전	출시 후보 버전	베타 버전	알파 버전
2026년 3월 11일	-	-	-	3.0.0-alpha01

종속 항목 선언

Room3의 종속 항목을 추가하려면 프로젝트에 Google Maven 저장소를 추가해야 합니다. 자세한 내용은 Google Maven 저장소를 읽어보세요.

다음과 같이 앱 또는 모듈의 build.gradle 파일에 필요한 아티팩트의 종속 항목을 추가합니다.

Kotlin

dependencies {
    val room_version = ""

    implementation("androidx.room3:room3-runtime:$room_version")
    ksp("androidx.room3:room3-compiler:$room_version")
}

Groovy

dependencies {
    def room_version = ""

    implementation "androidx.room3:room3-runtime:$room_version"

    ksp "androidx.room3:room3-compiler:$room_version"
}

KSP 플러그인 사용에 관한 자세한 내용은 KSP 빠른 시작 문서를 참고하세요.

종속 항목에 관한 자세한 내용은 빌드 종속 항목 추가를 참고하세요.

Room Gradle 플러그인 사용

Room Gradle 플러그인을 사용하여 Room 컴파일러의 옵션을 구성할 수 있습니다. 이 플러그인은 컴파일 작업의 출력이며 자동 이전에 사용되는 생성된 스키마가 재현 가능하고 캐시 가능한 빌드를 갖도록 올바르게 구성되도록 프로젝트를 구성합니다.

플러그인을 추가하려면 최상위 Gradle 빌드 파일에서 플러그인과 버전을 정의합니다.

Groovy

plugins {
    id 'androidx.room3' version "$room_version" apply false
}

Kotlin

plugins {
    id("androidx.room3") version "$room_version" apply false
}

모듈 수준 Gradle 빌드 파일에서 플러그인을 적용하고 room3 확장 프로그램을 사용합니다.

Groovy

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

Kotlin

plugins {
    id("androidx.room3")
}

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

Room Gradle 플러그인을 사용할 때는 schemaDirectory를 설정해야 합니다. 이렇게 하면 Room 컴파일러와 다양한 컴파일 작업 및 백엔드(kotlinc, KSP)가 스키마 파일을 schemas/flavorOneDebug/com.package.MyDatabase/1.json와 같은 플레이버 폴더에 출력하도록 구성됩니다. 이러한 파일은 유효성 검사 및 자동 이전에 사용되도록 저장소에 체크인해야 합니다.

의견

제출하신 의견은 Jetpack을 개선하는 데 도움이 됩니다. 새로운 문제를 발견하거나 라이브러리 개선을 위한 아이디어가 있다면 Google에 알려 주세요. 새 문제를 제출하기 전에 이 라이브러리의 기존 문제를 살펴보시기 바랍니다. 별표 버튼을 클릭하여 기존 문제에 투표할 수 있습니다.

새로운 문제 제출하기

자세한 내용은 Issue Tracker 문서를 참고하세요.

버전 3.0

버전 3.0.0-alpha01

2026년 3월 11일

androidx.room3:room3-*:3.0.0-alpha01이 출시되었습니다.

Room 3.0 (패키지 androidx.room3)은 Kotlin 멀티플랫폼 (KMP)에 중점을 둔 Room 2.x 패키지 (androidx.room)의 주요 버전 업데이트입니다.

핵심 주석 API는 주요 구성요소와 함께 동일하게 유지됩니다.

androidx.room3.RoomDatabase를 확장하고 @Database로 주석이 추가된 추상 클래스는 Room의 주석 프로세서 진입점입니다.
데이터베이스 선언에는 데이터베이스 스키마를 설명하는 데이터 클래스가 하나 이상 있으며 @Entity 주석이 달려 있습니다.
데이터베이스 작업은 @Query 주석을 통해 SQL 문이 정의된 쿼리 함수가 포함된 @Dao 선언에 정의됩니다.
런타임에 데이터베이스 구현은 데이터베이스를 구성하는 데도 사용되는 RoomDatabase.Builder를 통해 가져올 수 있습니다.

Room을 사용하여 로컬 데이터베이스에 데이터 저장 가이드의 대부분은 Room 3.0과 관련이 있습니다.

Room 2.x와의 주요 호환성 문제 차이점은 다음과 같습니다.

새 패키지 androidx.room3
androidx.room3:room3-sqlite-wrapper를 사용하지 않는 한 SupportSQLite API는 더 이상 지원되지 않습니다.
이제 모든 데이터베이스 작업이 코루틴 API를 기반으로 합니다.
Kotlin 코드 생성만 해당합니다.
Kotlin Symbol Processing (KSP)이 필요합니다.

브레이킹 체인지와 함께 Room 3.0에는 2.x에 비해 새로운 기능이 도입되었습니다.

JS 및 WasmJS 지원
맞춤 DAO 반환 유형

새 패키지

기존 Room 2.x 구현 및 Room에 전이 종속성이 있는 라이브러리 (예: WorkManager)와의 호환성 문제를 방지하기 위해 Room 3.0은 새 패키지에 상주합니다. 즉, 새 Maven 그룹과 아티팩트 ID도 있습니다. 예를 들어 androidx.room:room-runtime이 androidx.room3:room3-runtime로 변경되었으며 androidx.room.RoomDatabase과 같은 클래스는 이제 androidx.room3.RoomDatabase에 있습니다.

SupportSQLite API 없음

Room 3.0은 SQLiteDriver API로 완전히 지원되며 더 이상 SupportSQLiteDatabase와 같은 SupportSQLite 유형이나 Cursor과 같은 Android 유형을 참조하지 않습니다. SupportSQLiteDatabase을 미러링하는 RoomDatabase API와 SupportSQLiteOpenHelper를 가져오는 API가 삭제되었으므로 Room 3.0과 2.x 간의 가장 중요한 변경사항입니다. 이제 RoomDatabase을 빌드하려면 SQLiteDriver이 필요합니다.

예를 들어 직접 데이터베이스 작업을 위한 API는 드라이버에 상응하는 API로 대체됩니다.

// Room 2.x
roomDatabase.runInTransaction { ... }

// Room 3.x
roomDatabase.withWriteTransaction { ... }

// Room 2.x
roomDatabase.query("SELECT * FROM Song").use { cursor -> ... }

// Room 3.x
roomDatabase.useReaderConnection { connection ->
  connection.usePrepared("SELECT * FROM Song") { stmt -> ... }
}

SupportSQLiteDatabase를 인수로 사용하는 콜백 API도 SQLiteConnection를 인수로 사용하는 상응하는 API로 대체되었습니다. Migration.onMigrate(), AutoMigrationSpec.onPostMigrate()과 같은 마이그레이션 콜백 함수와 RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen()과 같은 데이터베이스 콜백이 있습니다.

KMP 프로젝트에서 Room을 사용한 경우 가져오기 참조를 업데이트하는 것이 대부분이므로 3.0으로 이전하는 것이 더 간단합니다. 그렇지 않으면 Android 전용에서 KMP로의 Room과 동일한 이전 전략이 적용됩니다. Room KMP 이전 가이드를 참고하세요.

SupportSQLite 래퍼

Room 3.x는 마이그레이션을 용이하게 하기 위해 2.x에서 생성된 SupportSQLite 래퍼를 유지하며 이제 새로운 아티팩트 androidx.room3:room3-sqlite-wrapper에 있습니다. 호환성 API를 사용하면 RoomDatabase를 SupportSQLiteDatabase로 변환할 수 있습니다. roomDatabase.openHelper.writableDatabase 호출은 roomDatabase.getSupportWrapper()로 대체할 수 있습니다.

Kotlin 및 코루틴 우선

라이브러리를 더 효과적으로 발전시키기 위해 Room 3.0에서는 Kotlin 코드만 생성하며 Kotlin Symbol Processor (KSP)로만 작동합니다. Room 2.x와 비교할 때 Room 3.0에서는 Java 코드 생성이 없으며 KAPT 또는 JavaAP를 통한 주석 프로세서 구성이 더 이상 불가능합니다. KSP는 Java 소스를 처리할 수 있으며 Room 컴파일러는 소스 선언이 Java에 있는 데이터베이스, 엔티티 또는 DAO의 코드를 생성합니다. Room 사용이 집중되어 있고 Kotlin Gradle 플러그인과 KSP를 나머지 코드베이스에 영향을 주지 않고 적용할 수 있는 다중 모듈 프로젝트를 사용하는 것이 좋습니다.

Room 3.0에서는 코루틴도 사용해야 합니다. 특히 DAO 함수는 반응형 유형(예: Flow 또는 맞춤 DAO 반환 유형)을 반환하지 않는 한 일시 중단되어야 합니다. 데이터베이스 작업을 실행하는 Room API도 RoomDatabase.useReaderConnection 및 RoomDatabase.useWriterConnection과 같은 정지 함수입니다.

Room 2.x와 달리 더 이상 Executor로 RoomDatabase를 구성할 수 없습니다. 대신 디스패처와 함께 CoroutineContext를 데이터베이스 빌더를 통해 제공할 수 있습니다.

Room 3.0의 InvalidationTracker API는 Flow 기반이며 InvalidationTracker.Observer는 관련 API addObserver 및 removeObserver와 함께 삭제됩니다. 데이터베이스 작업에 반응하는 메커니즘은 InvalidationTracker의 createFlow() API를 통해 만들 수 있는 코루틴 흐름을 사용하는 것입니다.

사용 예:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
    return db.invalidationTracker.createFlow("Artist").map { _ ->
        val artists = artistsDao.getAllArtists()
        val tours = tourService.fetchStates(artists.map { it.id })
        associateTours(artists, tours, from, to)
    }
}

웹 지원

Room 3.0 출시에서는 JavaScript와 WasmJs가 KMP 타겟으로 추가되었습니다. JavaScript 및 WasmJs를 타겟팅하는 SQLiteDriver 인터페이스 (androidx.sqlite:sqlite)와 새 아티팩트 androidx.sqlite:sqlite-web에 있는 새 드라이버 WebWorkerSQLiteDriver의 출시와 결합하면 모든 주요 KMP 플랫폼을 타겟팅하는 공통 코드에서 Room을 사용할 수 있습니다.

웹 플랫폼의 비동기 특성으로 인해 SQLiteStatement를 인수로 사용하는 Room API가 이제 suspend 함수입니다. 이러한 함수의 예로는 Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() 등이 있습니다. 드라이버 API에서 비동기 API는 모든 플랫폼에서 일반적이고 동기 API는 웹이 아닌 타겟에서 일반적입니다. 따라서 웹을 타겟팅하지 않는 프로젝트는 공통 코드에서 동기 API (SQLiteDriver.open(), SQLiteConnection.prepare(), SQLiteStatement.step())를 계속 사용할 수 있습니다. 웹만 타겟팅하는 프로젝트는 비동기 API(SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync(), SQLiteStatement.stepAsync())를 사용해야 합니다.

편의를 위해 androidx.sqlite 패키지에는 언급된 API의 동기식 이름 (SQLiteConnection.executeSQL 추가)이 있는 중단 확장 함수도 추가되었습니다. 이러한 API는 프로젝트가 웹과 비웹 플랫폼을 모두 타겟팅하는 경우 권장됩니다. API가 플랫폼에 따라 올바른 변형을 호출하는 expect / actual 선언이기 때문입니다. 이러한 API는 Room의 런타임이 사용하며 지원되는 모든 플랫폼의 공통 코드에서 드라이버 사용을 지원합니다.

사용 예:

import androidx.sqlite.executeSQL
import androidx.sqlite.step

roomDatabase.useWriterConnection { connection ->
    val deletedSongs = connection.usePrepared(
        "SELECT count(*) FROM Song"
    ) { stmt ->
        stmt.step()
        stmt.getLong(0)
    }
    connection.executeSQL("DELETE FROM Song")
    deletedSongs
}

WebWorkerSQLiteDriver는 기본 스레드에서 데이터베이스 작업을 실행하기 위해 웹 작업자와 통신하고 Origin Private File System (OPFS)에 데이터베이스를 저장할 수 있는 SQLiteDriver의 구현입니다. 드라이버를 인스턴스화하려면 간단한 통신 프로토콜을 구현하는 작업자가 필요합니다. 프로토콜은 WebWorkerSQLiteDriver KDoc에 설명되어 있습니다.

현재 WebWorkerSQLiteDriver는 통신 프로토콜을 구현하는 기본 작업자와 함께 제공되지 않지만, 예를 들어 androidx 코드베이스에는 프로젝트에서 사용할 수 있는 작업자 구현이 포함되어 있습니다. SQLite의 WASM을 사용하고 데이터베이스를 OPFS에 저장합니다. 예시 작업자는 로컬 NPM 패키지로 게시되며 NPM 종속 항목에 대한 Kotlin 지원 덕분에 작업자를 제공하는 작은 KMP 모듈을 만들 수 있습니다.

Room의 로컬 웹 작업자 사용을 보여주는 다음 GitHub 프로젝트를 참고하세요.

프로젝트에 작업자가 설정되면 웹용 Room 구성은 다른 플랫폼과 유사합니다.

fun createDatabase(): MusicDatabase {
    return Room.databaseBuilder<MusicDatabase>("music.db")
        .setDriver(WebWorkerSQLiteDriver(createWorker()))
        .build()
}

fun createWorker() =
    Worker(js("""new URL("sqlite-web-worker/worker.js", import.meta.url)"""))

향후 버전의 웹 드라이버에는 NPM에 게시된 기본 작업자가 포함되어 웹 설정이 더 간단해질 수 있습니다.

맞춤 DAO 반환 유형

RxJava 및 Paging용과 같은 다양한 DAO 반환 유형 통합이 DAO 반환 유형 변환기라는 Room 3.0의 새로운 API를 사용하도록 변환되었습니다. DAO 반환 유형 변환기 함수 (@DaoReturnTypeConverter)를 사용하면 주석이 추가된 함수로 정의된 맞춤 유형으로 DAO 함수의 결과를 변환할 수 있습니다. 이러한 함수를 사용하면 쿼리 결과를 데이터 객체로 변환하는 Room의 생성된 코드에 참여할 수 있습니다. DAO 반환 유형 변환기가 포함된 클래스는 @Database 또는 @Dao 선언의 @DaoReturnTypeConverters 주석을 통해 등록해야 합니다.

예를 들어 DAO 쿼리가 PagingSource를 반환하도록 하려면 androidx.room3:room3-paging에 있는 변환기 클래스를 등록해야 합니다.

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song)
    fun getSongsPaginated(): PagingSource<Int, Song>
}

기존 통합이 DAO 반환 유형 변환기로 이동되었습니다.

반환 유형	변환기 클래스	아티팩트
PagingSource	PagingSourceDaoReturnTypeConverter	androidx.room3:room3-paging
Observable, Flowable, Completable, Single, Maybe	RxDaoReturnTypeConverters	androidx.room3:room3-rxjava3
ListenableFuture	GuavaDaoReturnTypeConverter	androidx.room3:room3-guava
LiveData	LiveDataDaoReturnTypeConverter	androidx.room3:room3-livedata

열 유형 변환기와 마찬가지로 DAO 반환 유형 변환기는 애플리케이션에서 정의할 수 있습니다. 예를 들어 애플리케이션은 웹 유형 kotlin.js.Promise에 대해 @DaoReturnTypeConverter을 선언할 수 있습니다.

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

위 변환기를 사용하면 DAO 쿼리 함수가 Promise를 반환할 수 있습니다.

@Dao
@DaoReturnTypeConverters(PromiseDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song")
    fun getAllSongs(): Promise<List<Song>>
}

@DaoReturnTypeConverter 함수에는 매개변수 수와 유형에 관한 몇 가지 요구사항이 있습니다. 가능한 매개변수는 다음과 같습니다.

db: RoomDatabase: (선택사항) 추가 데이터베이스 작업을 실행하거나 코루틴 범위에 액세스하는 데 유용할 수 있는 RoomDatabase 인스턴스에 대한 액세스를 제공합니다.
tableNames: Array<String>: (선택사항) 쿼리의 액세스된 테이블을 포함합니다. Room의 InvalidationTracker.createFlow() API와 결합될 때 관찰 가능한 / 반응형 유형을 지원하는 데 유용합니다.
rawQuery: RoomRawQuery: (선택사항) 런타임에 쿼리의 인스턴스를 포함하여 PagingSourceDaoReturnTypeConverter에서 구현한 LIMIT / OFFSET 전략과 같은 변환을 지원합니다.
executeAndConvert: suspend () -> T: (필수) 쿼리를 실행하고 결과를 데이터 객체로 파싱하는 Room 생성 함수입니다.

DAO 반환 유형 변환기를 만드는 데 필요한 요구사항에 관한 자세한 내용은 @DaoReturnTypeConverter API에 관한 KDoc을 참고하세요.