# androidx.room

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOSJavaScript

## Interfaces

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/PooledConnection` | A wrapper of `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteConnection` that belongs to a connection pool and is safe to use in a coroutine. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.QueryCallback` | Callback interface for when SQLite queries are executed. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabaseConstructor` | Defines a class that can instantiate the Room generated implementation of an 'abstract' `https://developer.android.com/reference/kotlin/androidx/room/Database` annotated `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` definition. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomOpenDelegateMarker` | Marker interface for Room's code generated delegate. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/TransactionScope` | A `https://developer.android.com/reference/kotlin/androidx/room/PooledConnection` with an active transaction capable of performing nested transactions. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Transactor` | A `https://developer.android.com/reference/kotlin/androidx/room/PooledConnection` that can perform transactions. | Cmn |

## Classes

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/DatabaseConfiguration` | Configuration class for a `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase`. | Cmn android N |
| `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker` | The invalidation tracker keeps track of tables modified by queries and notifies its created `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html`s about such modifications. | Cmn android N |
| `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker.Observer` | An observer that can listen for changes in the database by subscribing to an `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker`. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/MultiInstanceInvalidationService` | A `https://developer.android.com/reference/android/app/Service.html` for remote invalidation among multiple `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker` instances. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` | Base class for all Room databases. | Cmn android N |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Builder` | Builder for `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase`. | Cmn android N |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Callback` | Callback for `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` | Cmn android N |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.MigrationContainer` | A container to hold migrations. | Cmn android N |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.PrepackagedDatabaseCallback` | Callback for `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Builder#createFromAsset(kotlin.String)`, `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Builder#createFromFile(java.io.File)` and `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Builder#createFromInputStream(java.util.concurrent.Callable)` | android |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomRawQuery` | A query with an argument binding function. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomWarnings` | The list of warnings that are produced by Room. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RxRoom` |   | android |

## Exceptions

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/EmptyResultSetException` | Thrown by Room when the query in a `https://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Single.html` DAO method needs to return a result but the returned result from the database is empty. | android |

## Objects

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/FtsOptions` | Available option values that can be used with `https://developer.android.com/reference/kotlin/androidx/room/Fts3`\&`https://developer.android.com/reference/kotlin/androidx/room/Fts4`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Room` | Entry point for building and initializing a `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase`. | Cmn android N |

## Annotations

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/AutoMigration` | Declares an automatic migration on a Database. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/BuiltInTypeConverters` | Flags to turn on/off extra type converters provided by Room. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ColumnInfo` | Allows specific customization about the column associated with this property. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ColumnInfo.Collate` |   | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ColumnInfo.SQLiteTypeAffinity` | The SQLite column type constants that can be used in typeAffinity() | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ConstructedBy` | Defines the `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabaseConstructor` that will instantiate the Room generated implementation of the annotated `https://developer.android.com/reference/kotlin/androidx/room/Database`. | Cmn android N JS |
| `https://developer.android.com/reference/kotlin/androidx/room/Dao` | Marks the class as a Data Access Object. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Database` | Marks a class as a `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/DatabaseView` | Marks a class as an SQLite view. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Delete` | Marks a method in a `https://developer.android.com/reference/kotlin/androidx/room/Dao` annotated class as a delete method. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/DeleteColumn` | Repeatable annotation declaring the deleted columns in the `https://developer.android.com/reference/kotlin/androidx/room/AutoMigration#to()` version of an auto migration. | Cmn android |
| `https://developer.android.com/reference/kotlin/androidx/room/DeleteColumn.Entries` | Container annotation for the repeatable annotation `https://developer.android.com/reference/kotlin/androidx/room/DeleteColumn`. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/DeleteTable` | Repeatable annotation declaring the deleted tables in the `https://developer.android.com/reference/kotlin/androidx/room/AutoMigration#to()` version of an auto migration. | Cmn android |
| `https://developer.android.com/reference/kotlin/androidx/room/DeleteTable.Entries` | Container annotation for the repeatable annotation `https://developer.android.com/reference/kotlin/androidx/room/DeleteTable`. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/Embedded` | Marks a field of an `https://developer.android.com/reference/kotlin/androidx/room/Entity` or POJO to allow nested fields (i.e. fields of the annotated field's class) to be referenced directly in the SQL queries. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Entity` | Marks a class as an entity. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ExperimentalRoomApi` | APIs marked with ExperimentalRoomApi are experimental and may change. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/ForeignKey` | Declares a foreign key on another `https://developer.android.com/reference/kotlin/androidx/room/Entity`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ForeignKey.Action` | Constants definition for values that can be used in `https://developer.android.com/reference/kotlin/androidx/room/ForeignKey#onDelete()` and `https://developer.android.com/reference/kotlin/androidx/room/ForeignKey#onUpdate()`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Fts3` | Marks an `https://developer.android.com/reference/kotlin/androidx/room/Entity` annotated class as a FTS3 entity. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Fts4` | Marks an `https://developer.android.com/reference/kotlin/androidx/room/Entity` annotated class as a FTS4 entity. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Ignore` | Ignores the marked element from Room's processing logic. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room` | Declares an index on an `https://developer.android.com/reference/kotlin/androidx/room/Entity`. see: [SQLite Index Documentation](https://sqlite.org/lang_createindex.html) | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Insert` | Marks a method in a `https://developer.android.com/reference/kotlin/androidx/room/Dao` annotated class as an insert method. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Junction` | Declares a junction to be used for joining a relationship. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/MapColumn` | Declares which column is used to build a map or multimap return value in a `https://developer.android.com/reference/kotlin/androidx/room/Dao` query method. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/MapInfo` | **This annotation is deprecated.** Use @MapColumn instead. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/OnConflictStrategy` | Set of conflict handling strategies for various {@link Dao} methods. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/PrimaryKey` | Marks a field in an `https://developer.android.com/reference/kotlin/androidx/room/Entity` as the primary key. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ProvidedAutoMigrationSpec` | Marks a class as an auto migration spec that will be provided to Room at runtime. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/ProvidedTypeConverter` | Marks a class as a type converter that will be provided to Room at runtime. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Query` | Marks a method in a `Dao` annotated class as a query method. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RawQuery` | Marks a method in a `https://developer.android.com/reference/kotlin/androidx/room/Dao` annotated class as a raw query method where you can pass the query as a `https://developer.android.com/reference/kotlin/androidx/room/RoomRawQuery` or androidx.sqlite.db.SupportSQLiteQuery. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Relation` | A convenience annotation which can be used in a POJO to automatically fetch relation entities. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RenameColumn` | Repeatable annotation declaring the renamed columns in the `https://developer.android.com/reference/kotlin/androidx/room/AutoMigration#to()` version of an auto migration. | Cmn android |
| `https://developer.android.com/reference/kotlin/androidx/room/RenameColumn.Entries` | Container annotation for the repeatable annotation `https://developer.android.com/reference/kotlin/androidx/room/RenameColumn`. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/RenameTable` | Repeatable annotation declaring the renamed tables in the new version of an auto migration. | Cmn android |
| `https://developer.android.com/reference/kotlin/androidx/room/RenameTable.Entries` | Container annotation for the repeatable annotation `https://developer.android.com/reference/kotlin/androidx/room/RenameTable`. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/RewriteQueriesToDropUnusedColumns` | When present, `https://developer.android.com/reference/kotlin/androidx/room/RewriteQueriesToDropUnusedColumns` annotation will cause Room to rewrite your `https://developer.android.com/reference/kotlin/androidx/room/Query` methods such that only the columns that are used in the response are queried from the database. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/SkipQueryVerification` | Skips database verification for the annotated element. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Transaction` | Marks a method in a `https://developer.android.com/reference/kotlin/androidx/room/Dao` class as a transaction method. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/TypeConverter` | Marks a method as a type converter. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/TypeConverters` | Specifies additional type converters that Room can use. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Update` | Marks a method in a `https://developer.android.com/reference/kotlin/androidx/room/Dao` annotated class as an update method. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Upsert` | Marks a method in a `https://developer.android.com/reference/kotlin/androidx/room/Dao` annotated class as an upsert (insert or update) method. | Cmn |

## Enums

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/BuiltInTypeConverters.State` | Control flags for built in converters. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/FtsOptions.MatchInfo` |   | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/FtsOptions.Order` |   | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/Index.Order` |   | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.JournalMode` | Journal modes for SQLite database. | Cmn android N |
| `https://developer.android.com/reference/kotlin/androidx/room/Transactor.SQLiteTransactionType` | Transaction types. | Cmn |

## Extension functions summary

|---|---|---|
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room/Transactor.https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).deferredTransaction(kotlin.coroutines.SuspendFunction1)(block: suspend https://developer.android.com/reference/kotlin/androidx/room/TransactionScope<R>.() -> R)` Performs a `https://developer.android.com/reference/kotlin/androidx/room/Transactor.SQLiteTransactionType#DEFERRED` within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).deferredTransaction(kotlin.coroutines.SuspendFunction1)`. | Cmn |
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room/Transactor.https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).exclusiveTransaction(kotlin.coroutines.SuspendFunction1)(block: suspend https://developer.android.com/reference/kotlin/androidx/room/TransactionScope<R>.() -> R)` Performs a `https://developer.android.com/reference/kotlin/androidx/room/Transactor.SQLiteTransactionType#EXCLUSIVE` within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).exclusiveTransaction(kotlin.coroutines.SuspendFunction1)`. | Cmn |
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/PooledConnection.https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.PooledConnection).execSQL(kotlin.String)(sql: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Executes a single SQL statement that returns no values. | Cmn |
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room/Transactor.https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).immediateTransaction(kotlin.coroutines.SuspendFunction1)(block: suspend https://developer.android.com/reference/kotlin/androidx/room/TransactionScope<R>.() -> R)` Performs a `https://developer.android.com/reference/kotlin/androidx/room/Transactor.SQLiteTransactionType#IMMEDIATE` within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).immediateTransaction(kotlin.coroutines.SuspendFunction1)`. | Cmn |
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>>` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.[invalidationTrackerFlow](https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).invalidationTrackerFlow(kotlin.Array,kotlin.Boolean))( vararg tables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, emitInitialState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` **This function is deprecated.** Replaced by equivalent API in InvalidationTracker. | android |
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)(block: suspend (https://developer.android.com/reference/kotlin/androidx/room/Transactor) -> R)` Acquires a READ connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. | Cmn |
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)(block: suspend (https://developer.android.com/reference/kotlin/androidx/room/Transactor) -> R)` Acquires a WRITE connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. | Cmn |
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)(block: suspend () -> R)` Calls the specified suspending `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` in a database transaction. | android |

## Extension functions

### Transactor.deferredTransaction

Cmn Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/Transactor.kt+function:deferredTransaction)

```
suspend fun <R : Any?> Transactor.deferredTransaction(block: suspend TransactionScope<R>.() -> R): R
```

Performs a `https://developer.android.com/reference/kotlin/androidx/room/Transactor.SQLiteTransactionType#DEFERRED` within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).deferredTransaction(kotlin.coroutines.SuspendFunction1)`.

### Transactor.exclusiveTransaction

Cmn Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/Transactor.kt+function:exclusiveTransaction)

```
suspend fun <R : Any?> Transactor.exclusiveTransaction(block: suspend TransactionScope<R>.() -> R): R
```

Performs a `https://developer.android.com/reference/kotlin/androidx/room/Transactor.SQLiteTransactionType#EXCLUSIVE` within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).exclusiveTransaction(kotlin.coroutines.SuspendFunction1)`.

### PooledConnection.execSQL

Cmn Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/Transactor.kt+function:execSQL) Added in [2.7.0](https://developer.android.com/jetpack/androidx/releases/room#2.7.0)

```
suspend fun PooledConnection.execSQL(sql: String): Unit
```

Executes a single SQL statement that returns no values.

### Transactor.immediateTransaction

Cmn Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/Transactor.kt+function:immediateTransaction)

```
suspend fun <R : Any?> Transactor.immediateTransaction(block: suspend TransactionScope<R>.() -> R): R
```

Performs a `https://developer.android.com/reference/kotlin/androidx/room/Transactor.SQLiteTransactionType#IMMEDIATE` within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).immediateTransaction(kotlin.coroutines.SuspendFunction1)`.

### RoomDatabase.invalidationTrackerFlow

android Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/RoomDatabase.android.kt+function:invalidationTrackerFlow)

```
fun RoomDatabase.[invalidationTrackerFlow](https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).invalidationTrackerFlow(kotlin.Array,kotlin.Boolean))(
    vararg tables: String,
    emitInitialState: Boolean = true
): Flow<Set<String>>
```

> [!CAUTION]
> **This function is deprecated.**   
> Replaced by equivalent API in InvalidationTracker, use this instead:
>
> ```kotlin
> this.invalidationTracker.createFlow(*tables)
> ```

Creates a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` that listens for changes in the database via the `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker` and emits sets of the tables that were invalidated.

The Flow will emit at least one value, a set of all the tables registered for observation to kick-start the stream unless `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).invalidationTrackerFlow(kotlin.Array,kotlin.Boolean)` is set to `false`.

If one of the tables to observe does not exist in the database, this functions throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`.

The returned Flow can be used to create a stream that reacts to changes in the database:

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

| Parameters |
|---|---|
| `vararg tables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the tables or views to observe. |
| `emitInitialState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Set to `false` if no initial emission is desired. Default value is `true`. |

### RoomDatabase.useReaderConnection

Cmn Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/RoomDatabase.kt+function:useReaderConnection)

```
suspend fun <R : Any?> RoomDatabase.useReaderConnection(block: suspend (Transactor) -> R): R
```

Acquires a READ connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. A `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` will have one or more READ connections. The connection to use in the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` is an instance of `https://developer.android.com/reference/kotlin/androidx/room/Transactor` that provides the capabilities for performing nested transactions.

Using the connection after `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` completes is prohibited.

The connection will be confined to the coroutine on which `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` executes, attempting to use the connection from a different coroutine will result in an error.

If the current coroutine calling this function already has a confined connection, then that connection is used.

A connection is a limited resource and should not be held for more than it is needed. The best practice in using connections is to avoid executing long-running computations within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)`. If a caller has to wait too long to acquire a connection a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteException` will be thrown due to a timeout.

| Parameters |
|---|---|
| `block: suspend (https://developer.android.com/reference/kotlin/androidx/room/Transactor) -> R` | The code to use the connection. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteException` | when the database is closed or a thread confined connection needs to be upgraded or there is a timeout acquiring a connection. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` |   |

### RoomDatabase.useWriterConnection

Cmn Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/RoomDatabase.kt+function:useWriterConnection)

```
suspend fun <R : Any?> RoomDatabase.useWriterConnection(block: suspend (Transactor) -> R): R
```

Acquires a WRITE connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. A `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` will have only one WRITE connection. The connection to use in the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` is an instance of `https://developer.android.com/reference/kotlin/androidx/room/Transactor` that provides the capabilities for performing nested transactions.

Using the connection after `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` completes is prohibited.

The connection will be confined to the coroutine on which `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` executes, attempting to use the connection from a different coroutine will result in an error.

If the current coroutine calling this function already has a confined connection, then that connection is used as long as it isn't required to be upgraded to a writer. If an upgrade is required then a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteException` is thrown.

A connection is a limited resource and should not be held for more than it is needed. The best practice in using connections is to avoid executing long-running computations within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)`. If a caller has to wait too long to acquire a connection a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteException` will be thrown due to a timeout.

| Parameters |
|---|---|
| `block: suspend (https://developer.android.com/reference/kotlin/androidx/room/Transactor) -> R` | The code to use the connection. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteException` | when the database is closed or a thread confined connection needs to be upgraded or there is a timeout acquiring a connection. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` |   |

### RoomDatabase.withTransaction

android Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/RoomDatabase.android.kt+function:withTransaction)

```
suspend fun <R : Any?> RoomDatabase.withTransaction(block: suspend () -> R): R
```

Calls the specified suspending `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` in a database transaction. The transaction will be marked as successful unless an exception is thrown in the suspending `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` or the coroutine is cancelled.

Room will only perform at most one transaction at a time, additional transactions are queued and executed on a first come, first serve order.

Performing blocking database operations is not permitted in a coroutine scope other than the one received by the suspending block. It is recommended that all `https://developer.android.com/reference/kotlin/androidx/room/Dao` function invoked within the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` be suspending functions.

The internal dispatcher used to execute the given `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` will block an utilize a thread from Room's transaction executor until the `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` is complete.