# ForeignKey

Artifact: [androidx.room3:room3-common](https://developer.android.com/jetpack/androidx/releases/room3) [View Source](https://cs.android.com/search?q=file:androidx/room3/ForeignKey.kt+class:androidx.room3.ForeignKey) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

*** ** * ** ***


```
@Target(allowedTargets = )
@Retention(value = AnnotationRetention.BINARY)
public annotation ForeignKey
```

<br />

*** ** * ** ***

Declares a foreign key on another `https://developer.android.com/reference/androidx/room3/Entity`.

Foreign keys allows you to specify constraints across entities such that SQLite will ensure that the relationship is valid when you modify the database.

When a foreign key constraint is specified, SQLite requires the referenced columns to be part of a unique index in the parent table or the primary key of that table. You must create a unique index in the parent entity that covers the referenced columns. Room will verify this at compile time and output an error if it is missing.

It is also recommended to create an index on the child table to avoid full table scans when the parent table is modified. If a suitable index on the child table is missing, Room will output the `https://developer.android.com/reference/androidx/room3/RoomWarnings#MISSING_INDEX_ON_FOREIGN_KEY_CHILD()` warning.

A foreign key constraint can be deferred until the transaction is complete. This is useful if you are doing bulk inserts into the database in a single transaction. By default, foreign key constraints are immediate, but you can change this value by setting `https://developer.android.com/reference/androidx/room3/ForeignKey#deferred()` to `true`. You can also use [defer_foreign_keys](https://sqlite.org/pragma.html#pragma_defer_foreign_keys) to defer them depending on your transaction.

Please refer to the SQLite [foreign keys](https://sqlite.org/foreignkeys.html) documentation for details.

## Summary

| ### Nested types |
|---|
| `@https://developer.android.com/reference/androidx/annotation/IntDef(value = [1, 2, 3, 4, 5]) @https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.annotation/-retention/index.html(value = https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.annotation/-annotation-retention/-b-i-n-a-r-y/index.html) public annotation https://developer.android.com/reference/androidx/room3/ForeignKey.Action` Constants definition for values that can be used in `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` and `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`. |

| ### Constants |
|---|---|
| `static final int` | `https://developer.android.com/reference/androidx/room3/ForeignKey#CASCADE() = 5` Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`. |
| `static final int` | `https://developer.android.com/reference/androidx/room3/ForeignKey#NO_ACTION() = 1` Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`. |
| `static final int` | `https://developer.android.com/reference/androidx/room3/ForeignKey#RESTRICT() = 2` Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`. |
| `static final int` | `https://developer.android.com/reference/androidx/room3/ForeignKey#SET_DEFAULT() = 4` Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`. |
| `static final int` | `https://developer.android.com/reference/androidx/room3/ForeignKey#SET_NULL() = 3` Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`. |

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull String[]` | `https://developer.android.com/reference/androidx/room3/ForeignKey#getChildColumns()()` The list of column names in the current `https://developer.android.com/reference/androidx/room3/Entity`. |
| `final boolean` | `https://developer.android.com/reference/androidx/room3/ForeignKey#getDeferred()()` A foreign key constraint can be deferred until the transaction is complete. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?>` | `https://developer.android.com/reference/androidx/room3/ForeignKey#getEntity()()` The parent Entity to reference. |
| `final int` | `@https://developer.android.com/reference/androidx/room3/ForeignKey.Action https://developer.android.com/reference/androidx/room3/ForeignKey#getOnDelete()()` Action to take when the parent `https://developer.android.com/reference/androidx/room3/Entity` is deleted from the database. |
| `final int` | `@https://developer.android.com/reference/androidx/room3/ForeignKey.Action https://developer.android.com/reference/androidx/room3/ForeignKey#getOnUpdate()()` Action to take when the parent `https://developer.android.com/reference/androidx/room3/Entity` is updated in the database. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull String[]` | `https://developer.android.com/reference/androidx/room3/ForeignKey#getParentColumns()()` The list of column names in the parent `https://developer.android.com/reference/androidx/room3/Entity`. |

## Constants

### CASCADE

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

```
public static final int CASCADE = 5
```

Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`.

A `CASCADE` action propagates the delete or update operation on the parent key to each dependent child key. For `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` action, this means that each row in the child entity that was associated with the deleted parent row is also deleted. For an `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()` action, it means that the values stored in each dependent child key are modified to match the new parent key values.

### NO_ACTION

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

```
public static final int NO_ACTION = 1
```

Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`.

When a parent key is modified or deleted from the database, no special action is taken. This means that SQLite will not make any effort to fix the constraint failure, instead, reject the change.

### RESTRICT

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

```
public static final int RESTRICT = 2
```

Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`.

The `RESTRICT` action means that the application is prohibited from deleting (for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()`) or modifying (for `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`) a parent key when there exists one or more child keys mapped to it. The difference between the effect of a RESTRICT action and normal foreign key constraint enforcement is that the RESTRICT action processing happens as soon as the property is updated - not at the end of the current statement as it would with an immediate constraint, or at the end of the current transaction as it would with a `https://developer.android.com/reference/androidx/room3/ForeignKey#deferred()` constraint.

Even if the foreign key constraint is attached to is `https://developer.android.com/reference/androidx/room3/ForeignKey#deferred()`, configuring a `RESTRICT` action causes SQLite to return an error immediately if a parent key with dependent child keys is deleted or modified.

### SET_DEFAULT

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

```
public static final int SET_DEFAULT = 4
```

Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`.

The `SET DEFAULT` actions are similar to `https://developer.android.com/reference/androidx/room3/ForeignKey#SET_NULL()`, except that each of the child key columns is set to contain the columns default value instead of `NULL`.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/room3/ColumnInfo#defaultValue()` |   |

### SET_NULL

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

```
public static final int SET_NULL = 3
```

Possible value for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()` or `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`.

If the configured action is `SET NULL`, then when a parent key is deleted (for `https://developer.android.com/reference/androidx/room3/ForeignKey#onDelete()`) or modified (for `https://developer.android.com/reference/androidx/room3/ForeignKey#onUpdate()`), the child key columns of all rows in the child table that mapped to the parent key are set to contain `NULL` values.

## Public methods

### getChildColumns

```
public final @NonNull String[] getChildColumns()
```

The list of column names in the current `https://developer.android.com/reference/androidx/room3/Entity`.

Number of columns must match the number of columns specified in `https://developer.android.com/reference/androidx/room3/ForeignKey#(kotlin.reflect.KClass,kotlin.Array,kotlin.Array,kotlin.Int,kotlin.Int,kotlin.Boolean)`.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull String[]` | The list of column names in the current Entity. |

### getDeferred

```
public final boolean getDeferred()
```

A foreign key constraint can be deferred until the transaction is complete. This is useful if you are doing bulk inserts into the database in a single transaction. By default, foreign key constraints are immediate, but you can change it by setting this property to `true`. You can also use [defer_foreign_keys](https://sqlite.org/pragma.html#pragma_defer_foreign_keys) PRAGMA to defer them depending on your transaction.

| Returns |
|---|---|
| `boolean` | Whether the foreign key constraint should be deferred until the transaction is complete. Defaults to `false`. |

### getEntity

```
public final @NonNull KClass<@NonNull ?> getEntity()
```

The parent Entity to reference. It must be a class annotated with `https://developer.android.com/reference/androidx/room3/Entity` and referenced in the same database.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?>` | The parent Entity. |

### getOnDelete

```
@ForeignKey.Action
public final int getOnDelete()
```

Action to take when the parent `https://developer.android.com/reference/androidx/room3/Entity` is deleted from the database.

By default, `https://developer.android.com/reference/androidx/room3/ForeignKey#NO_ACTION()` is used.

Value is one of the following:

- `1`
- `2`
- `3`
- `4`
- `5`

<br />

| Returns |
|---|---|
| `int` | The action to take when the referenced entity is deleted from the database. |

### getOnUpdate

```
@ForeignKey.Action
public final int getOnUpdate()
```

Action to take when the parent `https://developer.android.com/reference/androidx/room3/Entity` is updated in the database.

By default, `https://developer.android.com/reference/androidx/room3/ForeignKey#NO_ACTION()` is used.

Value is one of the following:

- `1`
- `2`
- `3`
- `4`
- `5`

<br />

| Returns |
|---|---|
| `int` | The action to take when the referenced entity is updated in the database. |

### getParentColumns

```
public final @NonNull String[] getParentColumns()
```

The list of column names in the parent `https://developer.android.com/reference/androidx/room3/Entity`.

Number of columns must match the number of columns specified in `https://developer.android.com/reference/androidx/room3/ForeignKey#(kotlin.reflect.KClass,kotlin.Array,kotlin.Array,kotlin.Int,kotlin.Int,kotlin.Boolean)`.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull String[]` | The list of column names in the parent Entity. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/room3/ForeignKey#(kotlin.reflect.KClass,kotlin.Array,kotlin.Array,kotlin.Int,kotlin.Int,kotlin.Boolean)` |   |