# RoomDatabase

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.+class:androidx.room3.RoomDatabase) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOSJavaScript
- Cmn

  ```
  abstract class RoomDatabase
  ```

*** ** * ** ***

Base class for all Room databases. All classes that are annotated with `https://developer.android.com/reference/kotlin/androidx/room3/Database` must extend this class.

RoomDatabase provides direct access to the underlying database implementation, but you should prefer using `https://developer.android.com/reference/kotlin/androidx/room3/Dao` classes.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room3/Database` |   |

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.Builder<T : https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase>` Builder for `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase`. |
| `abstract class https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.Callback` Callback for `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase` |
| `enum https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.JournalMode : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-enum/index.html<https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.JournalMode>` Journal modes for SQLite database. |
| `class https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.MigrationContainer` A container to hold migrations. |
| `abstract class https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.PrepackagedDatabaseCallback` Callback for `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.Builder#createFromAsset(kotlin.String)`, `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.Builder#createFromFile(java.io.File)` and `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.Builder#createFromInputStream(java.util.concurrent.Callable)` |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#RoomDatabase()()` | Cmn android |

| ### Public functions |
|---|---|---|
| `abstract suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#clearAllTables()()` Deletes all rows from all the tables that are registered to this database as `https://developer.android.com/reference/kotlin/androidx/room3/Database#entities()`. | Cmn android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#close()()` Closes the database. | Cmn android |

| ### Public properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room3/InvalidationTracker` | `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#invalidationTracker()` The invalidation tracker for this database. | Cmn android |

| ### Extension functions |
|---|---|---|
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#(androidx.room3.RoomDatabase).useReaderConnection(kotlin.coroutines.SuspendFunction1)(block: suspend (https://developer.android.com/reference/kotlin/androidx/room3/Transactor) -> R)` Acquires a READ connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/kotlin/androidx/room3/package-summary#(androidx.room3.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/room3/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#(androidx.room3.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)(block: suspend (https://developer.android.com/reference/kotlin/androidx/room3/Transactor) -> R)` Acquires a WRITE connection, suspending while waiting if none is available and then calling the `https://developer.android.com/reference/kotlin/androidx/room3/package-summary#(androidx.room3.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/room3/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#(androidx.room3.RoomDatabase).withReadTransaction(kotlin.coroutines.SuspendFunction1)(block: suspend https://developer.android.com/reference/kotlin/androidx/room3/TransactionScope<R>.() -> R)` Acquire a READ connection and start a `https://developer.android.com/reference/kotlin/androidx/room3/Transactor.SQLiteTransactionType#DEFERRED` transaction to execute the given `https://developer.android.com/reference/kotlin/androidx/room3/package-summary#(androidx.room3.RoomDatabase).withReadTransaction(kotlin.coroutines.SuspendFunction1)` within the transaction. | Cmn |
| `suspend R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#(androidx.room3.RoomDatabase).withWriteTransaction(kotlin.coroutines.SuspendFunction1)(block: suspend https://developer.android.com/reference/kotlin/androidx/room3/TransactionScope<R>.() -> R)` Acquire a WRITE connection and start a `https://developer.android.com/reference/kotlin/androidx/room3/Transactor.SQLiteTransactionType#IMMEDIATE` transaction to execute the given `https://developer.android.com/reference/kotlin/androidx/room3/package-summary#(androidx.room3.RoomDatabase).withWriteTransaction(kotlin.coroutines.SuspendFunction1)` within the transaction. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` | `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase#(androidx.room3.RoomDatabase).getSupportWrapper()()` Gets a new `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` implementation that is backed by a `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase` for compatibility with existing usages of `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase`. | android |

## Public constructors

### RoomDatabase

Cmn android Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

```
RoomDatabase()
```

## Public functions

### clearAllTables

Cmn android Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

```
abstract suspend fun clearAllTables(): Unit
```

Deletes all rows from all the tables that are registered to this database as `https://developer.android.com/reference/kotlin/androidx/room3/Database#entities()`.

This does NOT reset the auto-increment value generated by `https://developer.android.com/reference/kotlin/androidx/room3/PrimaryKey#autoGenerate()`.

After deleting the rows, Room will set a WAL checkpoint and run `VACUUM`. This means that the data is completely erased. The space will be reclaimed by the system if the amount surpasses the threshold of database file size.

See SQLite documentation for details. [FileFormat](https://www.sqlite.org/fileformat.html)

### close

Cmn android Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

```
fun close(): Unit
```

Closes the database.

Once a `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase` is closed it should no longer be used.

## Public properties

### invalidationTracker

Cmn android Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

```
val invalidationTracker: InvalidationTracker
```

The invalidation tracker for this database.

You can use the invalidation tracker to get notified when certain tables in the database are modified.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room3/InvalidationTracker` | The invalidation tracker for the database. |

## Extension functions

### RoomDatabase.useReaderConnection

Cmn 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)

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

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

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

### RoomDatabase.useWriterConnection

Cmn 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)

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

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

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

### RoomDatabase.withReadTransaction

Cmn 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)

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

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

This function is a shorthand of:

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

### RoomDatabase.withWriteTransaction

Cmn 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)

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

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

This function is a shorthand of:

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

### RoomDatabase.getSupportWrapper

android Artifact: [androidx.room3:room3-sqlite-wrapper](https://developer.android.com/jetpack/androidx/releases/room3) [View Source](https://cs.android.com/search?q=file:androidx/room3/support/RoomSupportSQLite.kt+function:getSupportWrapper)

```
fun RoomDatabase.getSupportWrapper(): SupportSQLiteDatabase
```

Gets a new `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` implementation that is backed by a `https://developer.android.com/reference/kotlin/androidx/room3/RoomDatabase` for compatibility with existing usages of `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase`.