Use unsupported SQL features
A typed Prisma query cannot express a required SQL feature.
Prisma · Function
Prisma.raw
Prisma.raw constructs raw SQL for use with Prisma Client raw-query methods. It is an unsafe escape hatch: manually assembled queries require database-specific parameter markers and careful handling of all dynamic input.
How it works
Prisma.raw constructs a raw SQL fragment or query string that can be passed to Prisma Client raw-query methods. Because Prisma cannot add parameter markers or safely interpolate values into a string built this way, callers must supply the database-specific markers and avoid incorporating untrusted input.
Syntax
Prisma.raw(query)Parameters
| Name | Type | Description |
|---|---|---|
query | string | The raw SQL string or fragment to construct. The documentation page does not specify a separately documented parameter type. |
Returns
A raw SQL value suitable for use with Prisma raw-query methods; the fetched documentation does not state a separate return type.
Key points
- Treat
Prisma.rawas an unsafe construction escape hatch, not as automatic protection against SQL injection. - It can be used when a raw query must be assembled into one complete string.
- A complete string built this way needs deliberate handling because the method is potentially dangerous.
- The caller must choose the correct placeholder syntax for the database.
Common mistakes
- Misusing
Prisma.rawcan make a raw query vulnerable to SQL injection. - Building one large query string with
Prisma.rawis potentially dangerous and requires care. - When constructing the string yourself, Prisma does not generate parameter markers; use the correct markers for your database.
Example: Construct a raw query
const query = Prisma.raw('SELECT * FROM "User" WHERE email = $1');
const users = await prisma.$queryRaw(query);Build a complete raw SQL string only when its contents and parameter markers are controlled; otherwise use the safer tagged-template form.
When to use it
Build a complete raw statement
A raw statement must be assembled as a single string using known, trusted SQL text.
Interview questions
QWhat is Prisma.raw used for?
Prisma.raw is an escape hatch for constructing raw SQL that can be supplied to Prisma raw-query methods. It is useful when a query cannot be expressed through Prisma's typed API, but it does not provide the same safety as a tagged template when misused.
Follow-up: How would you safely include a user-provided email? Use $queryRaw with a tagged template and interpolate the value as a parameter rather than concatenating it into a Prisma.raw string.
QWhat must you handle when building a raw query with Prisma.raw?
A string assembled with Prisma.raw must use the parameter-marker syntax required by the target database. Prisma cannot infer or insert those markers for a manually built raw string.
Follow-up: Why is this different from a tagged template? The tagged-template API can construct parameters for the database, while a manually assembled raw string leaves marker construction to the caller.
QWhat security risk is associated with Prisma.raw?
The function can be dangerous when dynamic or untrusted input is incorporated into the resulting SQL. The documentation specifically warns that misuse can make raw-query methods vulnerable to SQL injection.
Follow-up: What is the safer default? Prefer Prisma's typed query API, or use parameterized $queryRaw tagged templates when raw SQL is necessary.
Related
$queryRaw$executeRaw$queryRawUnsafe$executeRawUnsafe