androidx.room

Room is a Database Object Mapping library that makes it easy to access database on Android applications.

Rather than hiding the details of SQLite, Room tries to embrace them by providing convenient APIs to query the database and also verify such queries at compile time. This allows you to access the full power of SQLite while having the type safety provided by Java SQL query builders.

There are 3 major components in Room.

  • Database: This annotation marks a class as a database. It should be an abstract class that extends RoomDatabase. At runtime, you can acquire an instance of it via Room.databaseBuilder or Room.inMemoryDatabaseBuilder.

    The database class defines the list of entities and data access objects in the database. It is also the main access point for the underlying connection.

  • Entity: This annotation marks a class as a database row. For each Entity, a database table is created to hold the items. The Entity class must be referenced in the Database#entities array. Each field of the Entity (and its super class) is persisted in the database unless it is denoted otherwise (see Entity docs for details).
  • Dao: This annotation marks a class or interface as a Data Access Object. Data access objects are the main components of Room that are responsible for defining the methods that access the database. The class that is annotated with Database must have an abstract method that has 0 arguments and returns the class that is annotated with Dao. While generating the code at compile time, Room will generate an implementation of this class.

    Using Dao classes for database access rather than query builders or direct queries allows you to keep a separation between different components and easily mock the database access while testing your application.

Below is a sample of a simple database.
// File: Song.java
@Entity
public class Song {
  @PrimaryKey
  private int id;
  private String name;
  @ColumnInfo(name = "release_year")
  private int releaseYear;
  // getters and setters are ignored for brevity but they are required for Room to work.
}
// File: SongDao.java
@Dao
public interface SongDao {
  @Query("SELECT * FROM song")
  List<Song> loadAll();
  @Query("SELECT * FROM song WHERE id IN (:songIds)")
  List<Song> loadAllBySongId(int... songIds);
  @Query("SELECT * FROM song WHERE name LIKE :name AND release_year = :year LIMIT 1")
  Song loadOneByNameAndReleaseYear(String first, int year);
  @Insert
  void insertAll(Song... songs);
  @Delete
  void delete(Song song);
}
// File: MusicDatabase.java
@Database(entities = {Song.class})
public abstract class MusicDatabase extends RoomDatabase {
  public abstract SongDao songDao();
}
You can create an instance of MusicDatabase as follows:
MusicDatabase db = Room
    .databaseBuilder(getApplicationContext(), MusicDatabase.class, "database-name")
    .build();
Since Room verifies your queries at compile time, it also detects information about which tables are accessed by the query or what columns are present in the response.

You can observe a particular table for changes using the InvalidationTracker class which you can acquire via RoomDatabase.getInvalidationTracker.

For convenience, Room allows you to return LiveData from Query methods. It will automatically observe the related tables as long as the LiveData has active observers.

// This live data will automatically dispatch changes as the database changes.
@Query("SELECT * FROM song ORDER BY name LIMIT 5")
LiveData<Song> loadFirstFiveSongs();

You can also return arbitrary data objects from your query results as long as the fields in the object match the list of columns in the query response. This makes it very easy to write applications that drive the UI from persistent storage.

class IdAndSongHeader {
  int id;
  @ColumnInfo(name = "header")
  String header;
}
// DAO
@Query("SELECT id, name || '-' || release_year AS header FROM song")
public IdAndSongHeader[] loadSongHeaders();
If there is a mismatch between the query result and the POJO, Room will print a warning during compilation.

Please see the documentation of individual classes for details.

Annotations

AutoMigration

Declares an automatic migration on a Database.

BuiltInTypeConverters

Flags to turn on/off extra type converters provided by Room.

ColumnInfo

Allows specific customization about the column associated with this field.

ColumnInfo.Collate
ColumnInfo.SQLiteTypeAffinity

The SQLite column type constants that can be used in typeAffinity()

Dao

Marks the class as a Data Access Object.

Database

Marks a class as a RoomDatabase.

DatabaseView

Marks a class as an SQLite view.

Delete

Marks a method in a Dao annotated class as a delete method.

DeleteColumn

Repeatable annotation declaring the deleted columns in the AutoMigration.to version of an auto migration.

DeleteColumn.Entries

Container annotation for the repeatable annotation DeleteColumn.

DeleteTable

Repeatable annotation declaring the deleted tables in the AutoMigration.to version of an auto migration.

DeleteTable.Entries

Container annotation for the repeatable annotation DeleteTable.

Embedded

Marks a field of an Entity or POJO to allow nested fields (i.e. fields of the annotated field's class) to be referenced directly in the SQL queries.

Entity

Marks a class as an entity.

ExperimentalRoomApi

APIs marked with ExperimentalRoomApi are experimental and may change.

ForeignKey

Declares a foreign key on another Entity.

ForeignKey.Action

Constants definition for values that can be used in onDelete and onUpdate.

Fts3

Marks an Entity annotated class as a FTS3 entity.

Fts4

Marks an Entity annotated class as a FTS4 entity.

Ignore

Ignores the marked element from Room's processing logic.

Index

Declares an index on an Entity. see: SQLite Index Documentation

Insert

Marks a method in a Dao annotated class as an insert method.

Junction

Declares a junction to be used for joining a relationship.

MapColumn

Declares which column is used to build a map or multimap return value in a Dao query method.

MapInfo

This annotation is deprecated. Use @MapColumn instead.

OnConflictStrategy

Set of conflict handling strategies for various {@link Dao} methods.

PrimaryKey

Marks a field in an Entity as the primary key.

ProvidedAutoMigrationSpec

Marks a class as an auto migration spec that will be provided to Room at runtime.

ProvidedTypeConverter

Marks a class as a type converter that will be provided to Room at runtime.

Query

Marks a method in a Dao annotated class as a query method.

RawQuery

Marks a method in a Dao annotated class as a raw query method where you can pass the query as a androidx.sqlite.db.SupportSQLiteQuery.

Relation

A convenience annotation which can be used in a POJO to automatically fetch relation entities.

RenameColumn

Repeatable annotation declaring the renamed columns in the AutoMigration.to version of an auto migration.

RenameColumn.Entries

Container annotation for the repeatable annotation RenameColumn.

RenameTable

Repeatable annotation declaring the renamed tables in the new version of an auto migration.

RenameTable.Entries

Container annotation for the repeatable annotation RenameTable.

RewriteQueriesToDropUnusedColumns

When present, RewriteQueriesToDropUnusedColumns annotation will cause Room to rewrite your Query methods such that only the columns that are used in the response are queried from the database.

SkipQueryVerification

Skips database verification for the annotated element.

Transaction

Marks a method in a Dao class as a transaction method.

TypeConverter

Marks a method as a type converter.

TypeConverters

Specifies additional type converters that Room can use.

Update

Marks a method in a Dao annotated class as an update method.

Upsert

Marks a method in a Dao annotated class as an upsert (insert or update) method.

Interfaces

RoomDatabase.QueryCallback

Callback interface for when SQLite queries are executed.

Classes

DatabaseConfiguration

Configuration class for a RoomDatabase.

InvalidationTracker

InvalidationTracker keeps a list of tables modified by queries and notifies its callbacks about these tables.

InvalidationTracker.Observer

An observer that can listen for changes in the database.

MultiInstanceInvalidationService

A Service for remote invalidation among multiple InvalidationTracker instances.

RoomDatabase

Base class for all Room databases.

RoomDatabase.Builder

Builder for RoomDatabase.

RoomDatabase.Callback

Callback for RoomDatabase.

RoomDatabase.MigrationContainer

A container to hold migrations.

RoomDatabase.PrepackagedDatabaseCallback

Callback for Builder.createFromAsset, Builder.createFromFile and Builder.createFromInputStream

RoomDatabaseKt
RoomWarnings

The list of warnings that are produced by Room.

RxRoom

Helper class to add RxJava2 support to Room.

FtsOptions

Available option values that can be used with Fts3&Fts4.

Room

Utility functions for Room.

Enums

BuiltInTypeConverters.State

Control flags for built in converters.

FtsOptions.MatchInfo
FtsOptions.Order
Index.Order
RoomDatabase.JournalMode

Journal modes for SQLite database.

Exceptions

EmptyResultSetException

Thrown by Room when the query in a Single DAO method needs to return a result but the returned result from the database is empty.