Single-row inserts
Creating a new record from application data.
Drizzle ORM · Module
.values
.values() supplies one row object or an array of row objects to a Drizzle insert builder. Drizzle maps the objects to table columns and parameterizes the supplied values.
How it works
.values() supplies the row data for an insert query. It accepts one object for a single row or an array of objects for multiple rows; Drizzle maps the properties to table columns and parameterizes the supplied values before sending SQL to the database.
Syntax
db.insert(table).values(row)
db.insert(table).values(rows)Parameters
| Name | Type | Description |
|---|---|---|
values | Insert row object | Insert row object[] | One object containing column values for a row, or an array of such objects for multiple rows. |
Returns
An insert query builder; executing it inserts the supplied row or rows. Supported dialects can chain returning methods to retrieve inserted data.
Key points
- Use
.values()as the row-data part of a SQL-like insert builder. - A single object passed to
.values()inserts one row. - An array passed to
.values()inserts multiple rows in one insert operation. - Generated SQL uses a placeholder for supplied data and can use
defaultfor an omitted generated column.
Common mistakes
- Values are parameterized automatically, so they are not inserted as raw SQL text.
- Use the table's inferred insert type when you need an explicit type for insert data.
Example: Insert multiple rows with .values()
import { drizzle } from 'drizzle-orm/node-postgres';
import { pgTable, serial, text } from 'drizzle-orm/pg-core';
const users = pgTable('users', {
id: serial('id').primaryKey(),
name: text('name').notNull(),
});
const db = drizzle(process.env.DATABASE_URL!);
await db.insert(users).values([
{ name: 'Andrew' },
{ name: 'Dan' },
]);Inserts two rows using objects whose properties match the table columns.
When to use it
Bulk inserts
Loading several records efficiently in one insert statement.
Defaulted columns
Letting database-generated columns fill themselves when fields are omitted.
Interview questions
QWhat does .values() do in Drizzle ORM?
.values() provides the data for an insert operation. Pass one object for one row or an array of objects to insert multiple rows.
Follow-up: How are supplied values sent to the database? Drizzle parameterizes them automatically rather than embedding them directly in the generated SQL.
QHow do you insert multiple rows?
The object keys correspond to table columns, and omitted columns can use database defaults where the schema allows them. The insert remains type-checked against the table definition.
Follow-up: How can you name the insert payload type explicitly? Use typeof usersTable.$inferInsert.
QHow can insert values be typed for a table?
Call .values() with an array, such as [{ name: 'Andrew' }, { name: 'Dan' }]. Each array element represents one row.
Follow-up: How can an insert return inserted data? On supported dialects, chain .returning() or provide a selection object to return specific fields.
Related
insertreturning()$inferInsertonConflictDoNothing()onConflictDoUpdate()