Execute raw SQL
A SQLite write or other command that must run as raw SQL.
Drizzle ORM · Module
.run
For SQLite, db.run executes a raw parameterized SQL statement and returns the driver's run result. Use it when Drizzle's higher-level query API cannot express the required query.
How it works
For SQLite, use db.run with a parameterized SQL statement when you need to execute raw SQL that Drizzle's higher-level query APIs do not currently cover. The method returns the driver's run result rather than rows; use db.all, db.get, or db.values when reading data.
Syntax
db.run(statement)Parameters
| Name | Type | Description |
|---|---|---|
statement | SQL | A Drizzle SQL statement, typically created with the sql template tag. |
Returns
Database.RunResult
Key points
- SQLite exposes four raw-query helpers: db.run, db.all, db.values, and db.get.
- db.run returns the driver's Database.RunResult type.
- Use db.all when raw SQL should return an array of row results.
- Use db.get when raw SQL should return one result.
- Use db.values when raw SQL should return arrays of column values.
Common mistakes
- Use db.run for raw SQL cases outside Drizzle ORM's supported higher-level query construction.
- Choose the method according to the desired result shape; db.run is not the row-returning alternative.
Example: Run a raw SQL statement
import { sql } from 'drizzle-orm';
const statement = sql`delete from ${users} where ${users.id} = ${userId}`;
const result = db.run(statement);
Build a parameterized raw SQL statement with Drizzle's sql template and execute it with db.run.
When to use it
Handle unsupported SQL
A complex statement unsupported by Drizzle's higher-level query builder.
Interview questions
QWhat is db.run used for?
db.run executes a raw parameterized SQL statement against SQLite and returns the driver's run result. It is intended for statements where Drizzle's regular query API cannot express the required SQL.
Follow-up: How would you retrieve rows instead? Use db.all for row objects, db.get for one result, or db.values for value arrays.
QHow do you construct input for db.run?
The statement is created with Drizzle's sql template, which lets table columns and values participate in the SQL expression. The resulting statement is then passed to db.run.
Follow-up: Why prefer the sql template? It produces a parameterized statement instead of manually concatenating values into SQL.
QHow does db.run differ from the other raw SQL helpers?
db.run returns a Database.RunResult, while db.all, db.get, and db.values are the alternatives shown for queries that return data. Therefore, the appropriate method depends on whether the operation is a write or a read.
Follow-up: What should be used for a scalar or single-row lookup? Use db.get for a single returned value or record.
Related
sqldb.alldb.valuesdb.getDatabase.RunResult