Run custom SQL writes
A schema operation requires SQL that Prisma's model API does not express directly.
Prisma · Module
$executeRaw
$executeRaw runs one raw SQL operation and returns the number of affected rows, not records. Its tagged-template form supports parameterized values for safer execution.
How it works
Use Prisma Client's tagged-template method to execute one raw SQL write operation against a relational database. It returns the affected-row count rather than records, while interpolated values are escaped and sent as prepared-statement parameters.
Syntax
$executeRaw<T = unknown>(query: TemplateStringsArray | Prisma.Sql, ...values: any[]): PrismaPromise<number>;Parameters
| Name | Type | Description |
|---|---|---|
query | TemplateStringsArray | Prisma.Sql | The SQL template or a Prisma.Sql object representing the raw statement. |
values | any[] | Values interpolated into the raw SQL statement. |
Returns
PrismaPromise<number>, resolving to the number of affected rows.
Key points
- Use it for raw database writes when the useful result is an affected-row count.
- Typical operations include updating existing rows or deleting rows.
- After awaiting the Prisma promise, the result is a JavaScript number.
- The API is designed to be called with JavaScript tagged-template syntax.
- Interpolated variables are escaped by the tagged-template implementation.
- Tagged-template calls send SQL with parameters as prepared statements.
Common mistakes
- A single invocation supports only one SQL statement; appending another statement is not supported.
- Do not use $executeRaw when you need rows or selected columns; use a query-returning method instead.
Example: Update rows with $executeRaw
import { PrismaClient } from "@prisma/client";
const prisma = new PrismaClient();
async function main() {
const affected = await prisma.$executeRaw`
UPDATE User
SET active = true
WHERE emailValidated = true
`;
console.log(affected);
}
main()
.catch(console.error)
.finally(() => prisma.$disconnect());Runs a parameter-safe raw SQL update and logs the number of affected rows.
When to use it
Track affected-row counts
An UPDATE or DELETE should report how many rows changed.
Execute parameterized statements
A write uses interpolated application values.
Interview questions
QWhat does $executeRaw return?
$executeRaw executes raw SQL intended for operations such as UPDATE or DELETE and resolves to the number of affected rows. It does not return database records.
Follow-up: How should application values be supplied? Use the tagged-template form so Prisma escapes variables and sends the statement as a prepared statement.
QWhat is the method signature and result type?
Its signature accepts a template-string array or Prisma.Sql plus variadic values and returns a PrismaPromise<number>. The resolved number represents affected rows.
Follow-up: What limitation applies to the SQL text? One call can execute only one query, so multiple semicolon-separated statements are unsupported.
QWhy use the tagged-template syntax?
The recommended form is a tagged template, for example prisma.$executeRawUPDATE ... WHERE id = ${id}. Tagged templates allow variables to be escaped and queries to be sent as prepared statements.
Follow-up: Why avoid manually concatenating values? String construction can undermine the protections provided by parameterized tagged-template execution.
Related
$queryRaw$executeRawUnsafePrisma.SqlTypedSQL