# android.arch.persistence.room added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions) # android.arch.persistence.room | The`android.arch`Architecture Components packages are no longer maintained. They have been superseded by the corresponding[androidx.\*](https://developer.android.com/jetpack/androidx/migrate)packages. See[androidx.room](https://developer.android.com/reference/androidx/room/package-summary)instead. Room is a Database Object Mapping library that makes it easy to access database on Android applications. Rather than hiding the detail 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](https://developer.android.com/reference/android/arch/persistence/room/Database): This annotation marks a class as a database. It should be an abstract class that extends[RoomDatabase](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase). At runtime, you can acquire an instance of it via[Room.databaseBuilder](https://developer.android.com/reference/android/arch/persistence/room/Room#databaseBuilder(android.content.Context, java.lang.Class, java.lang.String))or[Room.inMemoryDatabaseBuilder](https://developer.android.com/reference/android/arch/persistence/room/Room#inMemoryDatabaseBuilder(android.content.Context, java.lang.Class)). This 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](https://developer.android.com/reference/android/arch/persistence/room/Entity): This annotation marks a class as a database row. For each[Entity](https://developer.android.com/reference/android/arch/persistence/room/Entity), a database table is created to hold the items. The Entity class must be referenced in the[Database#entities](https://developer.android.com/reference/android/arch/persistence/room/Database#entities())array. Each field of the Entity (and its super class) is persisted in the database unless it is denoted otherwise (see[Entity](https://developer.android.com/reference/android/arch/persistence/room/Entity)docs for details). - [Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao): This annotation marks a class or interface as a Data Access Object. Data access objects are the main component of Room that are responsible for defining the methods that access the database. The class that is annotated with[Database](https://developer.android.com/reference/android/arch/persistence/room/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: User.java @Entity public class User { @PrimaryKey private int uid; private String name; @ColumnInfo(name = "last_name") private String lastName; // getters and setters are ignored for brevity but they are required for Room to work. } // File: UserDao.java @Dao public interface UserDao { @Query("SELECT * FROM user") List loadAll(); @Query("SELECT * FROM user WHERE uid IN (:userIds)") List loadAllByUserId(int... userIds); @Query("SELECT * FROM user where name LIKE :first AND last_name LIKE :last LIMIT 1") User loadOneByNameAndLastName(String first, String last); @Insert void insertAll(User... users); @Delete void delete(User user); } // File: AppDatabase.java @Database(entities = {User.java}) public abstract class AppDatabase extends RoomDatabase { public abstract UserDao userDao(); } ``` You can create an instance of`AppDatabase`as follows: ``` AppDatabase db = Room .databaseBuilder(getApplicationContext(), AppDatabase.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](https://developer.android.com/reference/android/arch/persistence/room/InvalidationTracker)class which you can acquire via[RoomDatabase.getInvalidationTracker](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase#getInvalidationTracker()). For convenience, Room allows you to return[LiveData](https://developer.android.com/reference/android/arch/lifecycle/LiveData)from[Query](https://developer.android.com/reference/android/arch/persistence/room/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 user ORDER BY name LIMIT 5") LiveData loadFirstFiveUsers(); ``` You can also return arbitrary Java 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 IdAndFullName { public int uid; @ColumnInfo(name = "full_name") public String fullName; } // DAO @Query("SELECT uid, name || lastName as full_name FROM user") public IdAndFullName[] loadFullNames(); ``` 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 |--------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [ColumnInfo](https://developer.android.com/reference/android/arch/persistence/room/ColumnInfo) | Allows specific customization about the column associated with this field. | | [ColumnInfo.Collate](https://developer.android.com/reference/android/arch/persistence/room/ColumnInfo.Collate) | | | [ColumnInfo.SQLiteTypeAffinity](https://developer.android.com/reference/android/arch/persistence/room/ColumnInfo.SQLiteTypeAffinity) | The SQLite column type constants that can be used in[typeAffinity()](https://developer.android.com/reference/android/arch/persistence/room/ColumnInfo#typeAffinity()) | | [Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao) | Marks the class as a Data Access Object. | | [Database](https://developer.android.com/reference/android/arch/persistence/room/Database) | Marks a class as a RoomDatabase. | | [Delete](https://developer.android.com/reference/android/arch/persistence/room/Delete) | Marks a method in a[Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao)annotated class as a delete method. | | [Embedded](https://developer.android.com/reference/android/arch/persistence/room/Embedded) | Can be used as an annotation on a field of an[Entity](https://developer.android.com/reference/android/arch/persistence/room/Entity)or`Pojo`to signal that nested fields (i.e. | | [Entity](https://developer.android.com/reference/android/arch/persistence/room/Entity) | Marks a class as an entity. | | [ForeignKey](https://developer.android.com/reference/android/arch/persistence/room/ForeignKey) | Declares a foreign key on another[Entity](https://developer.android.com/reference/android/arch/persistence/room/Entity). | | [ForeignKey.Action](https://developer.android.com/reference/android/arch/persistence/room/ForeignKey.Action) | Constants definition for values that can be used in[onDelete()](https://developer.android.com/reference/android/arch/persistence/room/ForeignKey#onDelete())and[onUpdate()](https://developer.android.com/reference/android/arch/persistence/room/ForeignKey#onUpdate()). | | [Ignore](https://developer.android.com/reference/android/arch/persistence/room/Ignore) | Ignores the marked element from Room's processing logic. | | [Index](https://developer.android.com/reference/android/arch/persistence/room) | Declares an index on an Entity. | | [Insert](https://developer.android.com/reference/android/arch/persistence/room/Insert) | Marks a method in a[Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao)annotated class as an insert method. | | [OnConflictStrategy](https://developer.android.com/reference/android/arch/persistence/room/OnConflictStrategy) | Set of conflict handling strategies for various[Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao)methods. | | [PrimaryKey](https://developer.android.com/reference/android/arch/persistence/room/PrimaryKey) | Marks a field in an[Entity](https://developer.android.com/reference/android/arch/persistence/room/Entity)as the primary key. | | [Query](https://developer.android.com/reference/android/arch/persistence/room/Query) | Marks a method in a[Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao)annotated class as a query method. | | [RawQuery](https://developer.android.com/reference/android/arch/persistence/room/RawQuery) | Marks a method in a[Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao)annotated class as a raw query method where you can pass the query as a[SupportSQLiteQuery](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteQuery). | | [Relation](https://developer.android.com/reference/android/arch/persistence/room/Relation) | A convenience annotation which can be used in a Pojo to automatically fetch relation entities. | | [SkipQueryVerification](https://developer.android.com/reference/android/arch/persistence/room/SkipQueryVerification) | Skips database verification for the annotated element. | | [Transaction](https://developer.android.com/reference/android/arch/persistence/room/Transaction) | Marks a method in a[Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao)class as a transaction method. | | [TypeConverter](https://developer.android.com/reference/android/arch/persistence/room/TypeConverter) | Marks a method as a type converter. | | [TypeConverters](https://developer.android.com/reference/android/arch/persistence/room/TypeConverters) | Specifies additional type converters that Room can use. | | [Update](https://developer.android.com/reference/android/arch/persistence/room/Update) | Marks a method in a[Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao)annotated class as an update method. | ## Classes |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| | [DatabaseConfiguration](https://developer.android.com/reference/android/arch/persistence/room/DatabaseConfiguration) | Configuration class for a[RoomDatabase](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase). | | [InvalidationTracker](https://developer.android.com/reference/android/arch/persistence/room/InvalidationTracker) | InvalidationTracker keeps a list of tables modified by queries and notifies its callbacks about these tables. | | [InvalidationTracker.Observer](https://developer.android.com/reference/android/arch/persistence/room/InvalidationTracker.Observer) | An observer that can listen for changes in the database. | | [Room](https://developer.android.com/reference/android/arch/persistence/room/Room) | Utility class for Room. | | [RoomDatabase](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase) | Base class for all Room databases. | | [RoomDatabase.Builder](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.Builder)\ | Builder for RoomDatabase. | | [RoomDatabase.Callback](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.Callback) | Callback for[RoomDatabase](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase). | | [RoomDatabase.MigrationContainer](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.MigrationContainer) | A container to hold migrations. | | [RoomWarnings](https://developer.android.com/reference/android/arch/persistence/room/RoomWarnings) | The list of warnings that are produced by Room. | | [RxRoom](https://developer.android.com/reference/android/arch/persistence/room/RxRoom) | Helper class to add RxJava2 support to Room. | ## Enums |----------------------------------------------------------------------------------------------------------------------------|------------------------------------| | [RoomDatabase.JournalMode](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.JournalMode) | Journal modes for SQLite database. | ## Exceptions |--------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------| | [EmptyResultSetException](https://developer.android.com/reference/android/arch/persistence/room/EmptyResultSetException) | Thrown by Room when the query needs to return a result (e.g. | - ## Annotations - [ColumnInfo](https://developer.android.com/reference/android/arch/persistence/room/ColumnInfo) - [ColumnInfo.Collate](https://developer.android.com/reference/android/arch/persistence/room/ColumnInfo.Collate) - [ColumnInfo.SQLiteTypeAffinity](https://developer.android.com/reference/android/arch/persistence/room/ColumnInfo.SQLiteTypeAffinity) - [Dao](https://developer.android.com/reference/android/arch/persistence/room/Dao) - [Database](https://developer.android.com/reference/android/arch/persistence/room/Database) - [Delete](https://developer.android.com/reference/android/arch/persistence/room/Delete) - [Embedded](https://developer.android.com/reference/android/arch/persistence/room/Embedded) - [Entity](https://developer.android.com/reference/android/arch/persistence/room/Entity) - [ForeignKey](https://developer.android.com/reference/android/arch/persistence/room/ForeignKey) - [ForeignKey.Action](https://developer.android.com/reference/android/arch/persistence/room/ForeignKey.Action) - [Ignore](https://developer.android.com/reference/android/arch/persistence/room/Ignore) - [Index](https://developer.android.com/reference/android/arch/persistence/room) - [Insert](https://developer.android.com/reference/android/arch/persistence/room/Insert) - [OnConflictStrategy](https://developer.android.com/reference/android/arch/persistence/room/OnConflictStrategy) - [PrimaryKey](https://developer.android.com/reference/android/arch/persistence/room/PrimaryKey) - [Query](https://developer.android.com/reference/android/arch/persistence/room/Query) - [RawQuery](https://developer.android.com/reference/android/arch/persistence/room/RawQuery) - [Relation](https://developer.android.com/reference/android/arch/persistence/room/Relation) - [SkipQueryVerification](https://developer.android.com/reference/android/arch/persistence/room/SkipQueryVerification) - [Transaction](https://developer.android.com/reference/android/arch/persistence/room/Transaction) - [TypeConverter](https://developer.android.com/reference/android/arch/persistence/room/TypeConverter) - [TypeConverters](https://developer.android.com/reference/android/arch/persistence/room/TypeConverters) - [Update](https://developer.android.com/reference/android/arch/persistence/room/Update) - ## Classes - [DatabaseConfiguration](https://developer.android.com/reference/android/arch/persistence/room/DatabaseConfiguration) - [InvalidationTracker](https://developer.android.com/reference/android/arch/persistence/room/InvalidationTracker) - [InvalidationTracker.Observer](https://developer.android.com/reference/android/arch/persistence/room/InvalidationTracker.Observer) - [Room](https://developer.android.com/reference/android/arch/persistence/room/Room) - [RoomDatabase](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase) - [RoomDatabase.Builder](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.Builder) - [RoomDatabase.Callback](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.Callback) - [RoomDatabase.MigrationContainer](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.MigrationContainer) - [RoomWarnings](https://developer.android.com/reference/android/arch/persistence/room/RoomWarnings) - [RxRoom](https://developer.android.com/reference/android/arch/persistence/room/RxRoom) - ## Enums - [RoomDatabase.JournalMode](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase.JournalMode) - ## Exceptions - [EmptyResultSetException](https://developer.android.com/reference/android/arch/persistence/room/EmptyResultSetException)