# RoomDatabaseKt

Added in 3.0.2

*** ** * ** ***


```
public final class RoomDatabaseKt
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `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/room3/RoomDatabaseKt#(androidx.room3.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/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/room3/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/room3/package-summary#(androidx.room3.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/room3/RoomDatabaseKt#(androidx.room3.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/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/room3/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/room3/package-summary#(androidx.room3.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/room3/RoomDatabaseKt#(androidx.room3.RoomDatabase).withReadTransaction(kotlin.coroutines.SuspendFunction1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/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/room3/TransactionScope<@https://developer.android.com/reference/androidx/annotation/NonNull R>, @https://developer.android.com/reference/androidx/annotation/NonNull R> block )` Acquire a READ connection and start a `https://developer.android.com/reference/androidx/room3/Transactor.SQLiteTransactionType#DEFERRED` transaction to execute the given `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.RoomDatabase).withReadTransaction(kotlin.coroutines.SuspendFunction1)` within the transaction. |
| `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/room3/RoomDatabaseKt#(androidx.room3.RoomDatabase).withWriteTransaction(kotlin.coroutines.SuspendFunction1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/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/room3/TransactionScope<@https://developer.android.com/reference/androidx/annotation/NonNull R>, @https://developer.android.com/reference/androidx/annotation/NonNull R> block )` Acquire a WRITE connection and start a `https://developer.android.com/reference/androidx/room3/Transactor.SQLiteTransactionType#IMMEDIATE` transaction to execute the given `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.RoomDatabase).withWriteTransaction(kotlin.coroutines.SuspendFunction1)` within the transaction. |

## Public methods

### useReaderConnection

Artifact: [androidx.room3:room3-runtime](https://developer.android.com/jetpack/androidx/releases/room3) [View Source](https://cs.android.com/search?q=file:androidx/room3/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/room3/package-summary#(androidx.room3.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. A `https://developer.android.com/reference/androidx/room3/RoomDatabase` will have one or more READ connections. The connection to use in the `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` is an instance of `https://developer.android.com/reference/androidx/room3/Transactor` that provides the capabilities for performing nested transactions.

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

The connection will be confined to the coroutine on which `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.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/room3/package-summary#(androidx.room3.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/room3/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/room3/package-summary#(androidx.room3.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` |   |

### useWriterConnection

Artifact: [androidx.room3:room3-runtime](https://developer.android.com/jetpack/androidx/releases/room3) [View Source](https://cs.android.com/search?q=file:androidx/room3/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/room3/package-summary#(androidx.room3.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` to use the connection once it is acquired. A `https://developer.android.com/reference/androidx/room3/RoomDatabase` will have only one WRITE connection. The connection to use in the `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` is an instance of `https://developer.android.com/reference/androidx/room3/Transactor` that provides the capabilities for performing nested transactions.

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

The connection will be confined to the coroutine on which `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.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/room3/package-summary#(androidx.room3.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/room3/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/room3/package-summary#(androidx.room3.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)` |   |

### withReadTransaction

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

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

Acquire a READ connection and start a `https://developer.android.com/reference/androidx/room3/Transactor.SQLiteTransactionType#DEFERRED` transaction to execute the given `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.RoomDatabase).withReadTransaction(kotlin.coroutines.SuspendFunction1)` within the transaction.

This function is a shorthand of:

```
roomDatabase.useReaderConnection { it.withTransaction(DEFERRED) { block() } }
```

### withWriteTransaction

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

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

Acquire a WRITE connection and start a `https://developer.android.com/reference/androidx/room3/Transactor.SQLiteTransactionType#IMMEDIATE` transaction to execute the given `https://developer.android.com/reference/androidx/room3/package-summary#(androidx.room3.RoomDatabase).withWriteTransaction(kotlin.coroutines.SuspendFunction1)` within the transaction.

This function is a shorthand of:

```
roomDatabase.useWriterConnection { it.withTransaction(IMMEDIATE) { block() } }
```