Create or refresh a record keyed by a unique identifier
Idempotent synchronization
Prisma · Function
prisma.upsert
upsert updates a record when its unique where selector matches; otherwise, it creates one. It accepts separate update and create branches and may use a native database upsert when the documented criteria are satisfied.
How it works
Call a model's upsert method with a unique where selector and separate update and create branches. Prisma updates the matching record when one exists; when none matches, it inserts the create data. Where the documented criteria are satisfied, Prisma can delegate the operation to the database as a native upsert.
Syntax
await prisma.<model>.upsert({
where: <unique selector>,
update: <update data>,
create: <create data>,
})Parameters
| Name | Type | Description |
|---|---|---|
where | WhereUniqueInput | A unique selector used to determine whether an existing record matches. |
update | UpdateInput | Data applied when the selected record already exists. |
create | CreateInput | Data inserted when no matching record exists. |
Returns
The created or updated record for the model.
Key points
- A matching record takes the update path.
- No match takes the create path.
- Prisma can delegate eligible upserts to the database rather than handling them entirely in the client.
- The documented native database-upsert support includes CockroachDB, PostgreSQL, and SQLite.
Common mistakes
- A database-level upsert requires the where clause to contain only one unique field.
- For database delegation, the unique value used to find the record must also be the same value supplied by create.
- The method is not available for required composite types; use update instead.
Example: Update or create a user
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
async function main() {
const user = await prisma.user.upsert({
where: { email: 'alice@prisma.io' },
update: { name: 'Alice Updated' },
create: { email: 'alice@prisma.io', name: 'Alice' },
})
console.log(user)
}
main().finally(() => prisma.$disconnect())The unique email identifies the record. Prisma updates the matching user; otherwise it creates one using the create branch.
When to use it
Ensure a default record exists while updating it when present
Initialization
Use a compound unique selector to target a record
Compound uniqueness
Interview questions
QWhat does Prisma Client upsert do?
It combines an update and a create operation. If a record satisfies where, Prisma applies update; if not, Prisma creates a record from create.
Follow-up: When can Prisma use a database upsert? It can do so when there are no nested queries, no nested-read selection, only one modified model, and the documented unique-field criteria are met.
QWhat are the main upsert options?
The where option identifies the candidate record, update describes changes to an existing record, and create describes the complete data for a new record.
Follow-up: Why must create repeat the unique selector in database-upsert cases? The database needs the inserted row's unique value to correspond to the conflict target used for matching.
QWhy does Prisma sometimes use a database upsert?
Native database upserts are faster than upserts handled by Prisma Client because the database performs the operation directly. Prisma uses them with CockroachDB, PostgreSQL, or SQLite when the criteria are met.
Follow-up: What happens when the criteria are not met? Prisma Client handles the upsert instead of delegating it to the database.
Related
createupdatefindUniqueWorking with compound IDs and unique constraints