In a Prisma 7 schema, how does a relation field differ from the relation scalar field named in @relation(fields: [...], references: [...])?
answer
- one of them never reaches the database
- the column Prisma Migrate creates
- fields here, references over there
- two sides, only one annotated
- a unique key makes it one-to-one
basics
~20 sA relation field such as user User exists only in the Prisma schema and client; the relation scalar field such as userId Int is the real foreign-key column, and @relation(fields: [userId], references: [id]) links them on the side holding the key.
solid answer
~50 sEvery Prisma relation has exactly two **relation fields**, one per model: `orders Order[]` on `User` and `user User` on `Order`. Neither becomes a column; they exist so Prisma Client can read and write across the relation. The model that stores the key carries `@relation(fields: [userId], references: [id])`. `fields` lists this model's **relation scalar field** (`userId Int`, the real foreign-key column), and `references` lists the field it points to on the other model, which must be an `@id` or `@unique` field. The `?` and `[]` modifiers set the cardinality: a list on one side makes it one-to-many, and a one-to-one needs `@unique` on the scalar field or `prisma validate` rejects the schema. When two relations connect the same pair of models, or a model points at itself (a user's referrer), both sides need the same relation name, such as `@relation("Referrals")`.
code
plaintext · 1 lineError parsing attribute "@relation": A one-to-one relation must use unique fields on the defining side. Either add an `@unique` attribute to the field `userId`, or change the relation to one-to-many.go deeper
Recall that relation fields such as user User live only in the schema and client, while userId Int is the real column. Know what fields and references each name.
Explain how the modifiers set cardinality, why a one-to-one needs @unique on its scalar, and why the side without the scalar must be optional.
Show you can read a validation error and fix it: missing back-relation, ambiguous or self relations needing names, and a missing index on a plain foreign-key scalar.
Discuss schema conventions a team should fix early, such as which side holds a one-to-one key and how relation names are chosen, since changing them later costs migrations and client churn.
## Two kinds of field on one relation A Prisma schema describes a link between two models with fields of two different kinds, and confusing them is the most common beginner mistake. - A **relation field** has another model as its type: `user User`, `profile Profile?`, `orders Order[]`. It exists only in the Prisma schema and in the generated client, where it lets you nest reads and writes. Prisma Migrate never creates a column for it. - A **relation scalar field** has an ordinary scalar type, such as `userId Int`. It is the foreign-key column that really exists in the table, and in the default `foreignKeys` relation mode Prisma Migrate adds the foreign-key constraint on it. Every relation needs **exactly two relation fields**, one on each model. If you write `user User @relation(...)` on `Order` and forget `orders Order[]` on `User`, `prisma validate` fails with a message that the relation field `user` is "missing an opposite relation field" and suggests running `prisma format`, which adds the missing back-relation for you. ## Reading the @relation attribute Only the side that stores the key is **annotated**: ```prisma model User { id Int @id @default(autoincrement()) email String @unique profile Profile? orders Order[] referredById Int? referredBy User? @relation("Referrals", fields: [referredById], references: [id]) referrals User[] @relation("Referrals") } model Profile { id Int @id @default(autoincrement()) bio String user User @relation(fields: [userId], references: [id]) userId Int @unique } model Order { id Int @id @default(autoincrement()) user User @relation(fields: [userId], references: [id]) userId Int } ``` The arguments read like a sentence: **`fields`** names the column(s) on *this* model, **`references`** names the column(s) they point to on the *other* model. Both are lists because a relation can span several columns; with a composite key you write `fields: [a, b], references: [x, y]` in matching order. The referenced fields must be the other model's `@id` or a `@unique` field, or together form its `@@id` or `@@unique`. That is why `references: [email]` works when `email` is `@unique`. The same attribute also takes `onDelete` and `onUpdate` (the referential actions), `map` (a custom foreign-key constraint name) and an optional relation `name`. ## Cardinality comes from the modifiers | Shape | Back side | Annotated side | | --- | --- | --- | | One-to-many | `orders Order[]` | `user User` plus `userId Int` | | Optional one-to-many | `orders Order[]` | `user User?` plus `userId Int?` | | One-to-one | `profile Profile?` | `user User` plus `userId Int @unique` | Three rules follow from the table: 1. The list side of a one-to-many is never optional; an empty list means no related rows. 2. In a one-to-one, the side **without** the scalar field must be optional, because one row has to exist before its partner. 3. A one-to-one needs `@unique` on the scalar field. Without it, `prisma validate` reports that "a one-to-one relation must use unique fields on the defining side" and offers two fixes: add `@unique` or make the relation one-to-many. In a one-to-one you may put the scalar on either model; Prisma accepts both. Put it on the dependent record, so a `User` can exist without a `Profile` but a `Profile` always belongs to a user. ## Naming relations: duplicates and self-relations Prisma pairs the two relation fields of a relation by their types. That breaks in two cases, and both are solved with a **relation name**, written identically on both sides: - **Two relations between the same models**, such as `writtenPosts` and `pinnedPost` between `User` and `Post`. Without names the validator reports an ambiguous relation. - **A self-relation**, where a model points at itself. The referral link above is a one-to-many self-relation: `referredBy` holds the key and `referrals` is the back side. Without `"Referrals"` on both, validation fails with "Ambiguous self relation detected". The referral scalar `referredById` is optional because the first user had no referrer, and it carries no `@unique` because many users can share one referrer. ## Practical consequences - Writes may go through either form: the relation field (`user: { connect: { id: 1 } }`) or the scalar (`userId: 1`), but not both in one data object. - On PostgreSQL, Prisma Migrate creates the foreign-key constraint but no index on a plain scalar such as `Order.userId`; only the `@unique` one gets an index. Add `@@index([userId])` when you query by it. - Renaming a relation field usually changes only the client API (an implicit many-to-many self-relation is the exception, because field order decides which join column is which). Renaming the scalar field changes a column, and Prisma Migrate generates a drop and an add rather than a rename unless `@map` keeps the old column name. Keeping the two kinds apart answers most relation questions: relation fields shape the client, scalar fields shape the table.
- Can @relation reference a field other than the primary key?Yes. `references` may name any `@unique` field, so `@relation(fields: [userEmail], references: [email])` works when `email` is unique. For a composite target, `fields` and `references` list the same number of fields in the same order, and together they must match the other model's `@@id` or `@@unique`. A non-unique target is rejected, because a foreign key has to identify exactly one row.
- Which side of a one-to-one should hold the scalar field in Prisma?Prisma accepts either side, as long as the scalar is `@unique` and the other side is optional (`profile Profile?`). Put it on the dependent record: `Profile.userId` means a user can exist without a profile, while a profile cannot exist without its user. Putting it on `User` makes the profile the independent row, which rarely matches the domain.
- Why does a referral self-relation need a name when an ordinary one-to-many does not?Prisma pairs relation fields by type. In a self-relation both `referredBy User?` and `referrals User[]` point at `User`, so Prisma cannot tell whether they form one relation or two, and validation fails as an ambiguous self relation. Writing `@relation("Referrals")` on both sides pairs them; the annotated side additionally carries `fields` and `references`.
- The user relation field becomes a user column in the Order table.
- fields and references must be written on both sides of a one-to-many relation.
- A one-to-one needs no @unique; the ? modifier alone makes it one-to-one.
- references can point at any column of the other model, unique or not.
- A self-relation needs no name because Prisma infers which field holds the key.