Insert & Upsert

Single insert, bulk insert, and upsert (ON CONFLICT) — all through the InsertBuilder. These are PostgreSQL-native operations, not hacked abstractions.

#Two ways to insert

For simple single-record inserts, use db.user.create(). For bulk inserts, upserts (ON CONFLICT), or shaped RETURNING, use the InsertBuilder via db.user.insert().

create() — simple

·Single record only
·Always returns full record
·No conflict handling
·Simplest API

insert() — powerful

·Single or bulk insert
·ON CONFLICT (upsert)
·Shaped RETURNING
·InsertBuilder pattern

#Single insert

4 lines


1const user = await db.user
2  .insert({ email: '[email protected]', name: 'Alice', role: 'USER' })
3  .execute();
4// Returns the created record (RETURNING *)

#Bulk insert

Insert multiple rows in a single SQL statement. This is much faster than inserting one at a time — one round trip instead of N.

10 lines


1const users = await db.user.insert([
2  { email: '[email protected]', name: 'Alice', role: 'USER' },
3  { email: '[email protected]', name: 'Bob', role: 'ADMIN' },
4  { email: '[email protected]', name: 'Charlie', role: 'USER' },
5]).executeMany();
6 
7// Generated SQL:
8// INSERT INTO "users" ("email", "name", "role")
9// VALUES ($1, $2, $3), ($4, $5, $6), ($7, $8, $9)
10// RETURNING *

#Upsert (ON CONFLICT DO UPDATE)

Insert a record, but if it conflicts with a unique constraint, update instead. This is PostgreSQL's native upsert — atomic, race-condition-free, and efficient. No "check if exists then insert or update" pattern needed.

TSupsert by email

14 lines


1await db.user
2  .insert({ email: '[email protected]', name: 'Alice' })
3  .onConflict({
4    columns: ['email'],                // which unique constraint to check
5    action: 'update',                  // what to do on conflict
6    set: { name: 'Alice Updated' },    // which fields to update
7  })
8  .execute();
9 
10// Generated SQL:
11// INSERT INTO "users" ("email", "name")
12// VALUES ($1, $2)
13// ON CONFLICT ("email") DO UPDATE SET "name" = $3
14// RETURNING *

#ON CONFLICT DO NOTHING

Skip the insert silently if it would conflict. Useful for idempotent operations — "insert this if it doesn't exist, otherwise do nothing."

7 lines


1await db.user
2  .insert({ email: '[email protected]', name: 'Alice' })
3  .onConflict({ columns: ['email'], action: 'nothing' })
4  .execute();
5 
6// If email '[email protected]' already exists → nothing happens
7// If it doesn't exist → record is inserted

#Shaped RETURNING

By default, RETURNING * returns all columns. Use .returning()to specify exactly which columns you want back — useful when you only need the generated ID and don't want to transfer the entire record.

9 lines


1const result = await db.user
2  .insert({ email: '[email protected]', name: 'X' })
3  .returning(['id', 'email'])
4  .execute();
5 
6// result: { id: '...', email: '[email protected]' } — no name, no timestamps
7 
8// Or return everything:
9.returning('*')  // this is the default

#Method reference

Method	Description
`db.model.insert(data)`	Start an insert operation (single or array)
`.onConflict({ columns, action, set? })`	Handle unique constraint conflicts
`.returning(cols)`	Specify which columns to return (default: `'*'`)
`.execute()`	Execute and return first row (single insert)
`.executeMany()`	Execute and return all rows (bulk insert)
`.toSQL()`	Compile to `{ sql, params }` without executing