Idempotent imports
An import may contain rows already present under a unique key, and duplicates should be ignored.
Drizzle ORM · Module
.onConflictDoNothing
onConflictDoNothing makes an insert a no-op when a conflict occurs. You can let the database infer the conflict or explicitly provide a target.
How it works
Call onConflictDoNothing after values() to make an insert a no-op when a conflict occurs. Without options, the database determines the applicable conflict; passing target identifies the column or constraint to use.
Syntax
onConflictDoNothing(config?: { target?: ... })Parameters
| Name | Type | Description |
|---|---|---|
config | { target?: ... } | Optional configuration object containing the conflict target. |
Returns
An insert query that skips insertion when the configured conflict occurs.
Key points
- The method is part of Drizzle ORM’s insert conflict-handling API.
- A conflicting insert becomes a no-op instead of changing existing data.
- Begin the operation with db.insert() and pass the target table.
- Provide the row data with values() before adding conflict behavior.
- Pass target in the options object to explicitly select users.id as the conflict target.
Common mistakes
- The insert is canceled rather than updated when a conflict is detected.
Example: Skip an insert on a targeted conflict
await db.insert(users)
.values({ id: 1, name: "John" })
.onConflictDoNothing({ target: users.id });Attempts the insert and skips it when the specified unique conflict occurs.
When to use it
Safe initialization
A setup routine repeatedly inserts the same seed records without replacing existing values.
Preserve existing records
A write should preserve the existing row whenever uniqueness prevents a new row.
Interview questions
QWhat does onConflictDoNothing do?
onConflictDoNothing makes an insert do nothing when a conflict occurs, instead of raising a conflict error or modifying the existing row. It is chained after values().
Follow-up: How can the conflict be narrowed? Pass an options object with target, such as target: users.id, to explicitly identify the conflict target.
QHow do you specify the conflict target?
The method can be called without arguments when the database should infer the applicable conflict. It also accepts an options object that explicitly specifies a target.
Follow-up: What should be checked when a targeted insert still conflicts? Verify that the target matches the table’s relevant unique or primary-key constraint.
QWhere does this method fit in an insert query?
A typical chain is db.insert(table).values(row).onConflictDoNothing(). The method belongs to the insert conflict-handling API documented alongside onConflictDoUpdate.
Follow-up: When should an application use update-on-conflict instead? Use onConflictDoUpdate when the existing row must be changed rather than silently retaining it.
Related
onConflictDoUpdateinsertvalues