Single-row creation
Create a single record from validated application input.
Drizzle ORM · Module
db.insert
Inserts one or more typed rows into a Drizzle table with an SQL-like builder. The same page also covers parameterization, insert-from-select, returned rows, and conflict-handling forms.
How it works
Call insert with a table, then provide either one object or an array of objects to values. The inferred insert type checks required and optional columns, while conflict handlers and returning can extend the operation where the dialect supports them.
Syntax
db.insert(table).values(values)Parameters
| Name | Type | Description |
|---|---|---|
table | Table | The table receiving the new row or rows. |
values | InsertValue | InsertValue[] | One insert object or an array of insert objects; values may also be supplied from a select form documented on the page. |
onConflictDoUpdate | Conflict configuration | Optional conflict target and update configuration for PostgreSQL, CockroachDB, and SQLite. |
Returns
A dialect-specific insert query builder; awaiting it executes the insert and resolves with the dialect's result, or with returned rows when returning is supported and requested.
Key points
- The insert builder mirrors SQL while retaining TypeScript checks from the declared table schema.
- The basic flow is to choose a table with insert and supply row data through values.
- Use the table's $inferInsert type when you want a reusable type for validated insert payloads.
- Pass an array to values to insert multiple records in a single insert operation.
- Conflict updates let an insert modify an existing row when the configured uniqueness condition is met.
- The insert page supports supplying a query builder for insert-from-select operations.
Common mistakes
- Values passed to values are parameterized automatically; do not treat this API as raw SQL string interpolation.
- Use onConflictDoNothing when a conflicting row should cause the insert to be skipped rather than updated.
- Insert-from-select uses a SELECT query in place of a VALUES clause, so its selected shape must match the inserted columns.
Example: Insert one or more rows
import { drizzle } from 'drizzle-orm/better-sqlite3';
import Database from 'better-sqlite3';
import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';
const users = sqliteTable('users', {
id: integer('id').primaryKey(),
name: text('name').notNull(),
});
const db = drizzle(new Database(':memory:'));
await db.insert(users).values({ id: 1, name: 'Ada' });
await db.insert(users).values([
{ id: 2, name: 'Lin' },
{ id: 3, name: 'Mina' },
]);Creates one row and then inserts two rows with the SQLite Drizzle query builder.
When to use it
Bulk insertion
Persist several records efficiently in one insert operation.
Insert from select
Populate a table from the result of a select query.
Conflict-aware writes
Ignore or update rows that violate a uniqueness constraint.
Interview questions
QHow do you insert one or multiple rows?
db.insert(table) starts an insert query, and values accepts either one row object or an array for multiple rows. Drizzle generates the SQL and parameterizes the supplied values.
Follow-up: How would you avoid failing on a duplicate key? Use onConflictDoNothing, optionally supplying a conflict target.
QHow can insert data be type-checked?
Define a type with typeof users.$inferInsert, then pass a value matching that inferred insert shape to values. This keeps application data aligned with the table schema.
Follow-up: What should be checked when a field is omitted? Verify whether the schema supplies a default or marks the field as optional for inserts.
QHow do you implement an upsert?
For PostgreSQL, CockroachDB, and SQLite, onConflictDoUpdate updates a conflicting row using a target and set object. The page also documents conditional targetWhere and setWhere clauses for more precise conflict handling.
Follow-up: How does MySQL differ? Its insert upsert form uses onDuplicateKeyUpdate rather than onConflictDoUpdate.
Related
$inferInsertvaluesreturningonConflictDoNothingonConflictDoUpdatesetWheretargetWhereonDuplicateKeyUpdate