# RoomDatabase

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.+class:androidx.room.RoomDatabase) Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.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/room/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/room/Dao` classes.

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

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Builder<T : https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>` Builder for `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase`. |
| `abstract class https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Callback` Callback for `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` |
| `enum https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.JournalMode : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-enum/index.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.JournalMode>` Journal modes for SQLite database. |
| `class https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.MigrationContainer` A container to hold migrations. |
| `abstract class 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)` |
| `fun interface https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.QueryCallback` Callback interface for when SQLite queries are executed. |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#RoomDatabase()()` You cannot create an instance of a database, instead, you should acquire it via #Room.databaseBuilder or #Room.inMemoryDatabaseBuilder. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#RoomDatabase()()` | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#RoomDatabase()()` | N |

| ### Public functions |
|---|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `[beginTransaction](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#beginTransaction())()` **This function is deprecated.** beginTransaction() is deprecated | android |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/WorkerThread https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#clearAllTables()()` Deletes all rows from all the tables that are registered to this database as `https://developer.android.com/reference/kotlin/androidx/room/Database#entities()`. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#close()()` Closes the database. | Cmn android N |
| `open https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteStatement` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#compileStatement(kotlin.String)(sql: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#compileStatement(kotlin.String)`. | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `[endTransaction](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#endTransaction())()` **This function is deprecated.** endTransaction() is deprecated | android |
| `open T?` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> [getTypeConverter](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#getTypeConverter(java.lang.Class))(klass: https://developer.android.com/reference/java/lang/Class.html<T>)` **This function is deprecated.** No longer called by generated implementation | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#inTransaction()()` Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#inTransaction()`. | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/CallSuper https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#init(androidx.room.DatabaseConfiguration)(configuration: https://developer.android.com/reference/kotlin/androidx/room/DatabaseConfiguration)` Called by Room when it is initialized. | android |
| `open https://developer.android.com/reference/android/database/Cursor.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#query(kotlin.String,kotlin.Array)(query: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?>?)` Convenience method to query the database with arguments. | android |
| `open https://developer.android.com/reference/android/database/Cursor.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#query(androidx.sqlite.db.SupportSQLiteQuery,android.os.CancellationSignal)(query: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteQuery, signal: https://developer.android.com/reference/android/os/CancellationSignal.html?)` Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#query(kotlin.String)`. | android |
| `open V` | `<V : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#runInTransaction(java.util.concurrent.Callable)(body: https://developer.android.com/reference/java/util/concurrent/Callable.html<V>)` Executes the specified `https://developer.android.com/reference/java/util/concurrent/Callable.html` in a database transaction. | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#runInTransaction(java.lang.Runnable)(body: https://developer.android.com/reference/java/lang/Runnable.html)` Executes the specified `https://developer.android.com/reference/java/lang/Runnable.html` in a database transaction. | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `[setTransactionSuccessful](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#setTransactionSuccessful())()` **This function is deprecated.** setTransactionSuccessful() is deprecated | android |

| ### Protected functions |
|---|---|---|
| `abstract https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#createInvalidationTracker()()` Creates the invalidation tracker | Cmn android N |
| `open https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper` | `[createOpenHelper](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#createOpenHelper(androidx.room.DatabaseConfiguration))(config: https://developer.android.com/reference/kotlin/androidx/room/DatabaseConfiguration)` **This function is deprecated.** No longer implemented by generated | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `[internalInitInvalidationTracker](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#internalInitInvalidationTracker(androidx.sqlite.db.SupportSQLiteDatabase))(db: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase)` **This function is deprecated.** No longer called by generated | android |

| ### Public properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#invalidationTracker()` The invalidation tracker for this database. | Cmn android N |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#isOpen()` True if database connection is open and initialized. | android |
| `open https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#openHelper()` The SQLite open helper used by this database. | android |
| `open https://developer.android.com/reference/java/util/concurrent/Executor.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#queryExecutor()` The Executor in use by this database for async queries. | android |
| `open https://developer.android.com/reference/java/util/concurrent/Executor.html` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#transactionExecutor()` The Executor in use by this database for async transactions. | android |

| ### Protected properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase?` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#mDatabase()` **This property is deprecated.** This property is always null and will be removed in a future version. | android |

| ### Extension functions |
|---|---|---|
| `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/RoomDatabase#(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/RoomDatabase#(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/RoomDatabase#(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/RoomDatabase#(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 |
| `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` | `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#(androidx.room.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/room/RoomDatabase` for compatibility with existing usages of `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase`. | android |

## Public constructors

### RoomDatabase

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
RoomDatabase()
```

You cannot create an instance of a database, instead, you should acquire it via #Room.databaseBuilder or #Room.inMemoryDatabaseBuilder.

### RoomDatabase

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

```
RoomDatabase()
```

### RoomDatabase

N Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
RoomDatabase()
```

## Public functions

### beginTransaction

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0) Deprecated in [2.1.0](https://developer.android.com/jetpack/androidx/releases/room#2.1.0)

```
open fun [beginTransaction](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#beginTransaction())(): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> beginTransaction() is deprecated, use this instead:
>
> ```kotlin
> runInTransaction(Runnable)
> ```

Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#beginTransaction()`.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

### clearAllTables

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
@WorkerThread
abstract fun clearAllTables(): Unit
```

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

This does NOT reset the auto-increment value generated by `https://developer.android.com/reference/kotlin/androidx/room/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 N Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

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

Closes the database.

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

### compileStatement

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open fun compileStatement(sql: String): SupportSQLiteStatement
```

Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#compileStatement(kotlin.String)`.

| Parameters |
|---|---|
| `sql: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The query to compile. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteStatement` | The compiled query. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

### endTransaction

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0) Deprecated in [2.1.0](https://developer.android.com/jetpack/androidx/releases/room#2.1.0)

```
open fun [endTransaction](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#endTransaction())(): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> endTransaction() is deprecated, use this instead:
>
> ```kotlin
> runInTransaction(Runnable)
> ```

Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#endTransaction()`.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

### getTypeConverter

android Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/room#2.3.0) Deprecated in [2.7.0](https://developer.android.com/jetpack/androidx/releases/room#2.7.0)

```
open fun <T : Any> [getTypeConverter](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#getTypeConverter(java.lang.Class))(klass: Class<T>): T?
```

> [!CAUTION]
> **This function is deprecated.**   
> No longer called by generated implementation

Gets the instance of the given Type Converter.

| Parameters |
|---|---|
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | The type of the expected Type Converter subclass. |
| `klass: https://developer.android.com/reference/java/lang/Class.html<T>` | The Type Converter class. |

| Returns |
|---|---|
| `T?` | An instance of T if it is provided in the builder. |

### inTransaction

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open fun inTransaction(): Boolean
```

Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#inTransaction()`. Returns true if current thread is in a transaction.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | True if there is an active transaction in current thread, false otherwise. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#inTransaction()` |   |

### init

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
@CallSuper
open fun init(configuration: DatabaseConfiguration): Unit
```

Called by Room when it is initialized.

| Parameters |
|---|---|
| `configuration: https://developer.android.com/reference/kotlin/androidx/room/DatabaseConfiguration` | The database configuration. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if initialization fails. |

### query

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open fun query(query: String, args: Array<Any?>?): Cursor
```

Convenience method to query the database with arguments.

| Parameters |
|---|---|
| `query: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The sql query |
| `args: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?>?` | The bind arguments for the placeholders in the query |

| Returns |
|---|---|
| `https://developer.android.com/reference/android/database/Cursor.html` | A Cursor obtained by running the given query in the Room database. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

### query

android Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/room#2.2.0)

```
open fun query(query: SupportSQLiteQuery, signal: CancellationSignal? = null): Cursor
```

Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#query(kotlin.String)`.

| Parameters |
|---|---|
| `query: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteQuery` | The Query which includes the SQL and a bind callback for bind arguments. |
| `signal: https://developer.android.com/reference/android/os/CancellationSignal.html? = null` | The cancellation signal to be attached to the query. |

| Returns |
|---|---|
| `https://developer.android.com/reference/android/database/Cursor.html` | Result of the query. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

### runInTransaction

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open fun <V : Any?> runInTransaction(body: Callable<V>): V
```

Executes the specified `https://developer.android.com/reference/java/util/concurrent/Callable.html` in a database transaction. The transaction will be marked as successful unless an exception is thrown in the `https://developer.android.com/reference/java/util/concurrent/Callable.html`.

Room will only perform at most one transaction at a time.

If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database, then it is best to use `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` along with `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).immediateTransaction(kotlin.coroutines.SuspendFunction1)` to perform transactional operations.

| Parameters |
|---|---|
| `<V : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?>` | The type of the return value. |
| `body: https://developer.android.com/reference/java/util/concurrent/Callable.html<V>` | The piece of code to execute. |

| Returns |
|---|---|
| `V` | The value returned from the `https://developer.android.com/reference/java/util/concurrent/Callable.html`. |

### runInTransaction

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open fun runInTransaction(body: Runnable): Unit
```

Executes the specified `https://developer.android.com/reference/java/lang/Runnable.html` in a database transaction. The transaction will be marked as successful unless an exception is thrown in the `https://developer.android.com/reference/java/lang/Runnable.html`.

Room will only perform at most one transaction at a time.

If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database, then it is best to use `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.RoomDatabase).useWriterConnection(kotlin.coroutines.SuspendFunction1)` along with `https://developer.android.com/reference/kotlin/androidx/room/package-summary#(androidx.room.Transactor).immediateTransaction(kotlin.coroutines.SuspendFunction1)` to perform transactional operations.

| Parameters |
|---|---|
| `body: https://developer.android.com/reference/java/lang/Runnable.html` | The piece of code to execute. |

### setTransactionSuccessful

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0) Deprecated in [2.1.0](https://developer.android.com/jetpack/androidx/releases/room#2.1.0)

```
open fun [setTransactionSuccessful](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#setTransactionSuccessful())(): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> setTransactionSuccessful() is deprecated, use this instead:
>
> ```kotlin
> runInTransaction(Runnable)
> ```

Wrapper for `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase#setTransactionSuccessful()`.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

## Protected functions

### createInvalidationTracker

Cmn android N Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
protected abstract fun createInvalidationTracker(): InvalidationTracker
```

Creates the invalidation tracker

An implementation of this function is generated by the Room processor. Note that this function is called when the `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` is initialized.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker` | A new invalidation tracker. |

### createOpenHelper

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0) Deprecated in [2.7.0](https://developer.android.com/jetpack/androidx/releases/room#2.7.0)

```
protected open fun [createOpenHelper](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#createOpenHelper(androidx.room.DatabaseConfiguration))(config: DatabaseConfiguration): SupportSQLiteOpenHelper
```

> [!CAUTION]
> **This function is deprecated.**   
> No longer implemented by generated

Creates the open helper to access the database. Generated class already implements this method. Note that this method is called when the RoomDatabase is initialized.

| Parameters |
|---|---|
| `config: https://developer.android.com/reference/kotlin/androidx/room/DatabaseConfiguration` | The configuration of the Room database. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper` | A new SupportSQLiteOpenHelper to be used while connecting to the database. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-not-implemented-error/index.html` | by default |

### internalInitInvalidationTracker

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0) Deprecated in [2.7.0](https://developer.android.com/jetpack/androidx/releases/room#2.7.0)

```
protected open fun [internalInitInvalidationTracker](https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#internalInitInvalidationTracker(androidx.sqlite.db.SupportSQLiteDatabase))(db: SupportSQLiteDatabase): Unit
```

> [!CAUTION]
> **This function is deprecated.**   
> No longer called by generated

Initialize invalidation tracker. Note that this method is called when the `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` is initialized and opens a database connection.

| Parameters |
|---|---|
| `db: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` | The database instance. |

## Public properties

### invalidationTracker

Cmn android N Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.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/room/InvalidationTracker` | The invalidation tracker for the database. |

### isOpen

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open val isOpen: Boolean
```

True if database connection is open and initialized.

When Room is configured with `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase.Builder#setAutoCloseTimeout(kotlin.Long,java.util.concurrent.TimeUnit)` the database is considered open even if internally the connection has been closed, unless manually closed.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the database connection is open, false otherwise. |

### openHelper

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open val openHelper: SupportSQLiteOpenHelper
```

The SQLite open helper used by this database.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` is configured with this database. |

### queryExecutor

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open val queryExecutor: Executor
```

The Executor in use by this database for async queries.

### transactionExecutor

android Added in [2.1.0](https://developer.android.com/jetpack/androidx/releases/room#2.1.0)

```
open val transactionExecutor: Executor
```

The Executor in use by this database for async transactions.

## Protected properties

### mDatabase

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0) Deprecated in [2.1.0](https://developer.android.com/jetpack/androidx/releases/room#2.1.0)

```
protected var mDatabase: SupportSQLiteDatabase?
```

> [!CAUTION]
> **This property is deprecated.**   
> This property is always null and will be removed in a future version.

## Extension functions

### 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/RoomDatabase#(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.

### RoomDatabase.getSupportWrapper

android Artifact: [androidx.room:room-sqlite-wrapper](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/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/room/RoomDatabase` for compatibility with existing usages of `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase`.