One-to-one and one-to-many relations
Connect a relation field to a scalar foreign key and referenced identifier.
Prisma · Const
@relation
@relation defines metadata for a Prisma relation field, including how scalar foreign keys map to referenced fields. It also supports relation naming and referential actions.
How it works
@relation annotates a relation field with metadata Prisma needs to connect models. It can identify the participating scalar fields, referenced fields, relation names, and database referential actions; its exact arguments depend on the relation shape and connector.
Syntax
@relation(name?, fields?, references?, onDelete?, onUpdate?)Parameters
| Name | Type | Description |
|---|---|---|
name | String | Optional relation name used to disambiguate relations; it must match on both sides and cannot be empty. |
fields | FieldReference[] | Scalar fields on the current model that store the relation foreign key. |
references | FieldReference[] | Fields on the related model referenced by the relation foreign key. |
onDelete | ReferentialAction | Database action applied when a related record is deleted. |
onUpdate | ReferentialAction | Database action applied when a related record is updated. |
Returns
No runtime return value; @relation is a Prisma schema attribute.
Key points
- @relation describes how a relation is represented rather than creating a standalone model field.
- For relational databases, the mapping corresponds to foreign-key and references constraints.
- Use it for certain one-to-one and one-to-many definitions, ambiguous relations, self-relations, and MongoDB many-to-many relations.
- Use relation metadata when you need to customize the underlying relation-table representation.
- A custom relation name may be chosen freely, but an empty string is invalid.
Common mistakes
- Put @relation on a field whose type is another model, not directly on the scalar foreign-key field.
- Relations between the same pair of models must use a shared, nonempty name on both sides to remove ambiguity.
- Define a relation field on each participating model; a lone relation field does not complete the schema relation.
Example: One-to-many relation
model User {
id Int @id @default(autoincrement())
posts Post[]
}
model Post {
id Int @id @default(autoincrement())
author User @relation(fields: [authorId], references: [id])
authorId Int
}The relation field points to User, while fields and references connect the scalar foreign key to the referenced identifier.
When to use it
Disambiguate multiple relations
Give two relations between the same models distinct identities.
Self-relations
Describe a model related to itself.
Referential actions
Customize deletion or update behavior for related records.
Interview questions
QWhat does @relation do?
@relation adds metadata to a relation field. In a typical one-to-many relation, fields identifies the local scalar foreign key and references identifies the target field it points to.
Follow-up: How would you model two relations between the same models? Add the name argument to both relation fields and use the same nonempty name on each side.
QWhen is @relation required?
The attribute is needed for one-to-one and one-to-many relations on one side together with the corresponding relation scalar. It is also required when relations need disambiguation, for self-relations, and for MongoDB many-to-many relations.
Follow-up: What must a one-to-one foreign key have? It needs a unique constraint so one related record cannot be linked to multiple records.
QWhat do fields and references mean?
A fully annotated relation commonly looks like author User @relation(fields: [authorId], references: [id]). The scalar authorId stores the foreign-key value, while id is the referenced field on User.
Follow-up: Which database concepts correspond to this mapping? It corresponds to foreign-key and references constructs in the database.
Related
relationsrelation fieldsrelation scalar fieldsreferential actionsrelation modes