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 |
Constants | |
---|---|
int |
CASCADE
Possible value for |
int |
NO_ACTION
Possible value for |
int |
RESTRICT
Possible value for |
int |
SET_DEFAULT
Possible value for |
int |
SET_NULL
Possible value for |
Public methods | |
---|---|
String[]
|
childColumns()
The list of column names in the current |
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 |
int
|
onUpdate()
Action to take when the parent |
String[]
|
parentColumns()
The list of column names in the parent |
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:
Annotations
Classes
Enums
Exceptions
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-11 UTC.