Room 3.0

종속 항목 선언

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

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

dependencies {
    val room_version = ""

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

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 빌드 파일에서 플러그인과 버전을 정의합니다.

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

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

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

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

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-alpha04

2026년 5월 6일

androidx.room3:room3-*:3.0.0-alpha04가 출시되었습니다. 버전 3.0.0-alpha04에 포함된 커밋을 확인하세요.

API 변경사항

• Room의 연결 풀을 구성하는 API를 추가합니다. 빌더 함수 setSingleConnectionPool() 및 setMultipleConnectionPool()을 사용하여 Room이 데이터베이스에 여는 최대 연결 수를 제어할 수 있습니다. (I9700d, b/438041176, b/432820350)
• 다른 공개 API가 구성을 참조하지 않으므로 공개 API에서 Room의 DatabaseConfiguration을 삭제합니다. (I5f1e9, b/438041176)

버전 3.0.0-alpha03

2026년 4월 8일

androidx.room3:room3-*:3.0.0-alpha03가 출시되었습니다. 버전 3.0.0-alpha03에 포함된 커밋을 확인하세요.

API 변경사항

• @Database 선언에서 생성자가 참조될 때 Lint 경고가 표시되지 않도록 RoomDatabase의 인수가 없는 생성자를 공개합니다. (I9bac2, b/494722261)
• Android 컨텍스트를 사용하지 않는 Room.inMemoryDatabaseBuilder 및 Room.databaseBuilder 버전을 추가합니다. Room 3.0에서는 컨텍스트의 필요성이 크게 줄어들었으므로 빌더의 선택적 값으로 만들면 일반 코드에서 메모리 내 데이터베이스를 더 쉽게 만들 수 있습니다. (I5d502, b/438041176)

버그 수정

• onValidateSchema 함수의 본문이 너무 클 때 JVM 및 Android 생성 코드에서 '코드가 너무 큼' 오류를 수정합니다 (b/493708172).

버전 3.0.0-alpha02

2026년 3월 25일

androidx.room3:room3-*:3.0.0-alpha02가 출시되었습니다. 버전 3.0.0-alpha02에 포함된 커밋을 확인하세요.

새로운 기능

• FTS5 지원: @Fts5 주석을 통해 Room에 FTS5 지원을 추가했습니다. 여기에는 FTS5 토큰화기 (TOKENIZER_ASCII 및 TOKENIZER_TRIGRAM)의 새 상수와 '세부정보' FTS 옵션 (FULL, COLUMN, NONE)의 enum이 포함됩니다. (I90934, b/146824830)
• Room 페이징 타겟: room3-paging에 js, wasmJs, tvOS, watchOS 타겟을 추가했습니다. (Icffd3, b/432783733)

API 변경사항

• 멀티 플랫폼 clearAllTables(): clearAllTables()를 일반화하여 모든 플랫폼에서 사용할 수 있도록 했습니다. suspend 함수로도 변환되었습니다. (I434ae, b/322846465)
• 파괴적 마이그레이션: fallbackToDestructiveMigration API의 dropAllTables에 기본 파라미터 값을 추가했습니다. (Ica88b, b/438041176)

• 실험용 API 변경사항:

  1. 주석 기반 API를 실험용으로 표시할 수 있도록 @ExperimentalRoomApi를 room-common으로 이동했습니다.

  2. Room 데이터베이스 선언에서 @ConstructedBy의 요구사항을 억제하는 실험용 RoomWarning을 추가했습니다. 이 경우 DatabaseConstructor가 생성되지 않으며 DatabaseBuilder를 통해 팩토리 구현을 제공해야 합니다. (If5443)

버그 수정

• 페이징 소스: PagingSourceDaoReturnTypeConverter가 변환 함수가 읽기 쿼리를 위한 것임을 올바르게 나타내도록 업데이트했습니다. (I3b067, b/139872302)

버전 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로 주석이 지정됩니다.
• 데이터베이스 작업은 SQL 문이 @Query 주석을 통해 정의되는 쿼리 함수를 포함하는 @Dao 선언에 정의됩니다.
• 런타임 시 데이터베이스 구현은 데이터베이스를 구성하는 데도 사용되는 RoomDatabase.Builder를 통해 가져올 수 있습니다.

Room을 사용하여 로컬 데이터베이스에 데이터 저장 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에서 완전히 지원되며 더 이상 SupportSQLite 유형(예: SupportSQLiteDatabase)이나 Android 유형(예: Cursor)을 참조하지 않습니다. 이는 SupportSQLiteDatabase를 미러링한 RoomDatabase API가 SupportSQLiteOpenHelper를 가져오는 API와 함께 삭제되었으므로 Room 3.0과 2.x 간의 가장 중요한 변경사항입니다. 이제 RoomDatabase를 빌드하려면 SQLiteDriver가 필수 입니다.

예를 들어 직접 데이터베이스 작업의 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로 대체되었습니다. 이러한 콜백 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와 비교했을 때 Java 코드 생성이 없으며 Room 3.0에서는 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는 이제 정지 함수입니다. 이러한 함수의 예로는 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는 플랫폼을 기반으로 올바른 변형을 호출하는 expect / actual 선언이므로 프로젝트가 웹 플랫폼과 웹이 아닌 플랫폼을 모두 타겟팅할 때 이러한 API를 사용하는 것이 좋습니다. 이러한 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 패키지로 게시되며 Kotlin의 NPM 종속 항목 지원 덕분에 작업자를 제공하는 작은 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 및 페이징과 같은 다양한 DAO 반환 유형 통합이 Room 3.0에서 DAO 반환 유형 변환기라는 새 API를 사용하도록 변환되었습니다. DAO 반환 유형 변환기 함수 (@DaoReturnTypeConverter)를 사용하면 DAO 함수의 결과를 주석이 지정된 함수로 정의된 맞춤 유형으로 변환할 수 있습니다. 이러한 함수를 사용하면 쿼리 결과를 데이터 객체로 변환하는 Room의 생성된 코드에 참여할 수 있습니다. DAO 반환 유형 변환기가 포함된 클래스는 @DaoReturnTypeConverters 주석을 통해 @Database 또는 @Dao 선언에 등록해야 합니다.

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

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

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

열 유형 변환기와 마찬가지로 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 반환 유형 변환기 생성 요구사항에 관한 자세한 내용은 API의 @DaoReturnTypeConverter KDoc을 참고하세요.