Use database-specific SQL
A database-specific function, operator, or expression is unavailable through the query builder.
Drizzle ORM · Module
db.execute
db.execute runs raw SQL through Drizzle ORM. Use the sql template to interpolate schema objects and runtime values while keeping values parameterized.
How it works
db.execute runs a raw SQL statement represented by Drizzle’s sql template. Schema tables and columns are converted to escaped SQL identifiers, while interpolated runtime values become bound parameters rather than concatenated SQL text.
Syntax
await db.execute(statement)Parameters
| Name | Type | Description |
|---|---|---|
statement | SQL | A raw SQL statement, typically created with Drizzle’s sql tagged template. |
Returns
The database driver’s result for the executed SQL statement.
Key points
- Use
db.executewhen a query needs SQL that is not conveniently expressed through Drizzle’s relational or query-builder APIs. - Create the statement with the
sqltagged template and interpolate Drizzle table or column objects directly. - Execution is asynchronous: await the database call to obtain the driver’s result.
Common mistakes
- Use the
sqltemplate for runtime values so the query remains parameterized; do not construct SQL by string concatenation.
Example: Run a parameterized raw query
import { sql } from 'drizzle-orm';
const userId = 69;
const result = await db.execute(
sql`select * from ${users} where ${users.id} = ${userId}`,
);Build a parameterized SQL template with schema objects and a runtime value, then execute it through the database instance.
When to use it
Run parameterized raw SQL
A query needs hand-written SQL while still using Drizzle schema objects and bound values.
Inspect dialect-specific SQL
A statement must be inspected for its generated text and parameters for a particular database.
Interview questions
QWhat is db.execute used for?
db.execute sends a raw SQL statement to the configured database. The recommended form uses Drizzle’s sql template, which supports parameterized interpolation and escaped schema identifiers.
Follow-up: How should a runtime value be inserted safely? Interpolate it inside sql rather than concatenating it into a string; Drizzle emits it as a bound parameter.
QHow does Drizzle handle tables and columns in an sql template?
The sql template maps supplied tables and columns to their SQL syntax and escapes their names. It also appends the escaped table name to column references where required.
Follow-up: Why does dialect matter when inspecting generated SQL? SQL placeholder and identifier syntax can differ between database dialects.
QWhat does await db.execute(...) return?
The call returns the result produced by the database driver for the executed statement. The exact result shape is driver- and dialect-dependent, so the page demonstrates awaiting the result rather than prescribing one universal row type.
Follow-up: What should be used when repeatedly executing the same query? Consider Drizzle prepared statements, whose execute method can be invoked repeatedly with placeholder values.
Related
sqlsql.placeholderprepareexecute