The Room persistence library provides an abstraction layer over SQLite to allow for more robust database access while harnessing the full power of SQLite.

[User Guide]

[API Reference]

To add a dependency on Room, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

dependencies {
    val room_version = "2.8.4"
    implementation("androidx.room:room-runtime:$room_version")
    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    ksp("androidx.room:room-compiler:$room_version")
    // optional - Kotlin Extensions and Coroutines support for Room
    implementation("androidx.room:room-ktx:$room_version")
    // optional - RxJava2 support for Room
    implementation("androidx.room:room-rxjava2:$room_version")
    // optional - RxJava3 support for Room
    implementation("androidx.room:room-rxjava3:$room_version")
    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation("androidx.room:room-guava:$room_version")
    // optional - Test helpers
    testImplementation("androidx.room:room-testing:$room_version")
    // optional - Paging 3 Integration
    implementation("androidx.room:room-paging:$room_version")
}

dependencies {
    def room_version = "2.8.4"
    implementation "androidx.room:room-runtime:$room_version"
    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    ksp "androidx.room:room-compiler:$room_version"
    // If this project only uses Java source, use the Java annotationProcessor
    annotationProcessor "androidx.room:room-compiler:$room_version"
    // optional - RxJava2 support for Room
    implementation "androidx.room:room-rxjava2:$room_version"
    // optional - RxJava3 support for Room
    implementation "androidx.room:room-rxjava3:$room_version"
    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "androidx.room:room-guava:$room_version"
    // optional - Test helpers
    testImplementation "androidx.room:room-testing:$room_version"
    // optional - Paging 3 Integration
    implementation "androidx.room:room-paging:$room_version"
}

For information on using the KAPT plugin, see the KAPT documentation.

For information on using the KSP plugin, see the KSP quick-start documentation.

For information on using Kotlin extensions, see the ktx documentation.

For more information about dependencies, see Add Build Dependencies.

Optionally, for non-Android libraries (i.e. Java or Kotlin only Gradle modules) you can depend on androidx.room:room-common to use Room annotations.

Room has the following annotation processor options.

With Room version 2.6.0 and higher, you can use the Room Gradle Plugin to configure options for the Room compiler. The plugin configures the project such that generated schemas (which are an output of the compile tasks and are consumed for auto-migrations) are correctly configured to have reproducible and cacheable builds.

To add the plugin, in your top-level Gradle build file, define the plugin and its version.

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

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

In the module-level Gradle build file, apply the plugin and use the room extension.

plugins {
    id("androidx.room")
}

android {
    // ...
    room {
        schemaDirectory("$projectDir/schemas")
    }
}

plugins {
    id 'androidx.room'
}

android {
    // ...
    room {
        schemaDirectory "$projectDir/schemas"
    }
}

Setting a schemaDirectory is required when using the Room Gradle Plugin. This will configure the Room compiler and the various compile tasks and its backends (javac, KAPT, KSP) to output schema files into flavored folders, for example schemas/flavorOneDebug/com.package.MyDatabase/1.json. These files should be checked into the repository to be used for validation and auto-migrations.

Some options cannot be configured in all versions of the Room Gradle Plugin, even though they are supported by the Room compiler. The table below lists each option and shows the version of the Room Gradle Plugin that added support for configuring that option using the room extension. If your version is lower, or if the option is not supported yet, you can use annotation processor options instead.

If you aren't using the Room Gradle Plugin, or if the option you want isn't supported by your version of the plugin, you can configure Room using annotation processor options, as described in Add build dependencies. How you specify annotation options depends on whether you use KSP or KAPT for Room.

// For KSP
ksp {
    arg("option_name", "option_value")
    // other options...
}

// For javac and KAPT
android {
    // ...
    defaultConfig {
        // ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf(
                    "option_name" to "option_value",
                    // other options...
                )
            }
        }
    }
}

// For KSP
ksp {
    arg("option_name", "option_value")
    // other options...
}

// For javac and KAPT
android {
    // ...
    defaultConfig {
        // ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += [
                    "option_name":"option_value",
                    // other options...
                ]
            }
        }
    }
}

Because room.schemaLocation is a directory and not a primitive type, it is necessary to use a CommandLineArgumentsProvider when adding this option so that Gradle knows about this directory when conducting up-to-date checks. Migrate your Room database shows a complete implementation of CommandLineArgumentsProvider that provides the schema location.

Issue Tracker