ForeignKey

public abstract @interface ForeignKey
implements Annotation

android.arch.persistence.room.ForeignKey

Declares a foreign key on another 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 print 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 print 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 deferred() to true. You can also use defer_foreign_keys PRAGMA to defer them depending on your transaction.

Please refer to the SQLite foreign keys documentation for details.

Summary

Nested classes

@interface ForeignKey.Action

Constants definition for values that can be used in onDelete() and onUpdate(). 

Constants

int CASCADE

Possible value for onDelete() or onUpdate().

int NO_ACTION

Possible value for onDelete() or onUpdate().

int RESTRICT

Possible value for onDelete() or onUpdate().

int SET_DEFAULT

Possible value for onDelete() or onUpdate().

int SET_NULL

Possible value for onDelete() or onUpdate().

Public methods

String[] childColumns()

The list of column names in the current Entity.

boolean deferred()

* A foreign key constraint can be deferred until the transaction is complete.

Class entity()

The parent Entity to reference.

int onDelete()

Action to take when the parent Entity is deleted from the database.

int onUpdate()

Action to take when the parent Entity is updated in the database.

String[] parentColumns()

The list of column names in the parent Entity.

Inherited methods

Constants

CASCADE

int CASCADE

Possible value for onDelete() or onUpdate().

A "CASCADE" action propagates the delete or update operation on the parent key to each dependent child key. For onDelete() action, this means that each row in the child entity that was associated with the deleted parent row is also deleted. For an onUpdate() action, it means that the values stored in each dependent child key are modified to match the new parent key values.

Constant Value: 5 (0x00000005)

NO_ACTION

int NO_ACTION

Possible value for onDelete() or 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.

Constant Value: 1 (0x00000001)

RESTRICT

int RESTRICT

Possible value for onDelete() or onUpdate().

The RESTRICT action means that the application is prohibited from deleting (for onDelete()) or modifying (for 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 field 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 deferred() constraint.

Even if the foreign key constraint it is attached to is deferred(), configuring a RESTRICT action causes SQLite to return an error immediately if a parent key with dependent child keys is deleted or modified.

Constant Value: 2 (0x00000002)

SET_DEFAULT

int SET_DEFAULT

Possible value for onDelete() or onUpdate().

The "SET DEFAULT" actions are similar to SET_NULL, except that each of the child key columns is set to contain the columns default value instead of NULL.

Constant Value: 4 (0x00000004)

SET_NULL

int SET_NULL

Possible value for onDelete() or onUpdate().

If the configured action is "SET NULL", then when a parent key is deleted (for onDelete()) or modified (for onUpdate()), the child key columns of all rows in the child table that mapped to the parent key are set to contain NULL values.

Constant Value: 3 (0x00000003)

Public methods

childColumns

String[] childColumns ()

The list of column names in the current Entity.

Number of columns must match the number of columns specified in parentColumns().

Returns
String[] The list of column names in the current Entity.

deferred

boolean deferred ()

* 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 field to true. You can also use 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.

entity

Class entity ()

The parent Entity to reference. It must be a class annotated with Entity and referenced in the same database.

Returns
Class The parent Entity.

onDelete

int onDelete ()

Action to take when the parent Entity is deleted from the database.

By default, NO_ACTION is used.

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

onUpdate

int onUpdate ()

Action to take when the parent Entity is updated in the database.

By default, NO_ACTION is used.

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

parentColumns

String[] parentColumns ()

The list of column names in the parent Entity.

Number of columns must match the number of columns specified in childColumns().

Returns
String[] The list of column names in the parent Entity.

See also: