# RoomDatabaseKt

Added in 2.7.0

*** ** * ** ***


```
public final class RoomDatabaseKt
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Set.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html>>` | `[invalidationTrackerFlow](https://developer.android.com/reference/androidx/room/RoomDatabaseKt#(androidx.room.RoomDatabase).invalidationTrackerFlow(kotlin.Array,kotlin.Boolean))( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/RoomDatabase receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html... tables, boolean emitInitialState )` **This method is deprecated.** Replaced by equivalent API in InvalidationTracker. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull R` | `<R extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/room/RoomDatabaseKt#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/RoomDatabase receiver, @https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/Transactor, @https://developer.android.com/reference/androidx/annotation/NonNull R> block )` Acquires a READ connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull R` | `<R extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/room/RoomDatabaseKt#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/RoomDatabase receiver, @https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/Transactor, @https://developer.android.com/reference/androidx/annotation/NonNull R> block )` Acquires a WRITE connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull R` | `<R extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/room/RoomDatabaseKt#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/RoomDatabase receiver, @https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction0<@https://developer.android.com/reference/androidx/annotation/NonNull R> block )` Calls the specified suspending `https://developer.android.com/reference/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` in a database transaction. |

## Public methods

### invalidationTrackerFlow

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)

```
public static final @NonNull Flow<@NonNull Set<@NonNull String>> [invalidationTrackerFlow](https://developer.android.com/reference/androidx/room/RoomDatabaseKt#(androidx.room.RoomDatabase).invalidationTrackerFlow(kotlin.Array,kotlin.Boolean))(
    @NonNull RoomDatabase receiver,
    @NonNull String... tables,
    boolean emitInitialState
)
```

> [!CAUTION]
> **This method is deprecated.**   
> Replaced by equivalent API in InvalidationTracker, use this instead:
>
> ```
> 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/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/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:

```
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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html... tables` | The name of the tables or views to observe. |
| `boolean emitInitialState` | Set to `false` if no initial emission is desired. Default value is `true`. |

### useReaderConnection

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)

```
public static final @NonNull R <R extends Object> useReaderConnection(
    @NonNull RoomDatabase receiver,
    @NonNull SuspendFunction1<@NonNull Transactor, @NonNull R> block
)
```

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

Using the connection after `https://developer.android.com/reference/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/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/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/androidx/sqlite/SQLiteException` will be thrown due to a timeout.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/Transactor, @https://developer.android.com/reference/androidx/annotation/NonNull R> block` | The code to use the connection. |

| Throws |
|---|---|
| `https://developer.android.com/reference/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/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` |   |

### useWriterConnection

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)

```
public static final @NonNull R <R extends Object> useWriterConnection(
    @NonNull RoomDatabase receiver,
    @NonNull SuspendFunction1<@NonNull Transactor, @NonNull R> block
)
```

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

Using the connection after `https://developer.android.com/reference/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/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/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/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/androidx/sqlite/SQLiteException` will be thrown due to a timeout.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room/Transactor, @https://developer.android.com/reference/androidx/annotation/NonNull R> block` | The code to use the connection. |

| Throws |
|---|---|
| `https://developer.android.com/reference/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/androidx/room/package-summary#(androidx.room.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` |   |

### withTransaction

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)

```
public static final @NonNull R <R extends Object> withTransaction(
    @NonNull RoomDatabase receiver,
    @NonNull SuspendFunction0<@NonNull R> block
)
```

Calls the specified suspending `https://developer.android.com/reference/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/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/androidx/room/Dao` function invoked within the `https://developer.android.com/reference/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/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/androidx/room/package-summary#(androidx.room.RoomDatabase).withTransaction(kotlin.coroutines.SuspendFunction0)` is complete.