Prisma engines
This page gives an overview of the Prisma internals and how it works "under the hood".
Note that this page does not contain any practical information that is relevant for using Prisma. It rather aims at providing a mental model for what the Prisma toolkit actually is and how the different tools that are available to developers are structured.
If you're new to Prisma, be sure to check out the Quickstart and Introduction pages first.
Prisma engines
At the core of each module, there typically is a Prisma engine that implements the core set of functionality. Engines are implemented in Rust and expose a low-level API that is used by the higher-level interfaces.
A Prisma engine is the direct interface to the database, any higher-level interfaces always communicate with the database through the engine-layer.
As an example, Prisma Client connects to the query engine in order to read and write data in a database:
Using custom engine libraries or binaries
By default, all engine files are automatically downloaded into the node_modules/@prisma/engines
folder when you install or update prisma
, the Prisma CLI package. The query engine is also copied to the generated Prisma Client when you call prisma generate
.
You might want to use a custom library or binary file if:
- Automated download of engine files is not possible.
- You have created your own engine library or binary for testing purposes, or for an OS that is not officially supported.
Use the following environment variables to specify custom locations for your binaries:
PRISMA_QUERY_ENGINE_LIBRARY
(Query engine, library)PRISMA_QUERY_ENGINE_BINARY
(Query engine, binary)PRISMA_MIGRATION_ENGINE_BINARY
(Migration engine)PRISMA_INTROSPECTION_ENGINE_BINARY
(Introspection engine)PRISMA_FMT_BINARY
(fornpx prisma format
)
The PRISMA_FMT_BINARY
variable is used in versions 4.2.0 or lower.
Setting the environment variable
You can define environment variables globally on your machine or in the .env
file.
a) The .env
file
Add the environment variable to the .env
file.
PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix
Note: It is possible to use an
.env
file in a location outside theprisma
folder.
b) Global environment variable
Run the following command to set the environment variable globally (in this example, PRISMA_QUERY_ENGINE_BINARY
):
$export PRISMA_QUERY_ENGINE_BINARY=/custom/my-query-engine-unix
Test your environment variable
Run the following command to output the paths to all binaries:
$npx prisma -v
The output shows that the query engine path comes from the PRISMA_QUERY_ENGINE_BINARY
environment variable:
Current platform : darwinQuery Engine : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /custom/my-query-engine-unix)Migration Engine : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/engines/migration-engine-unix)Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/engines/introspection-engine-unix)Format Binary : prisma-fmt d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/engines/prisma-fmt-unix)
Hosting engines
The PRISMA_ENGINES_MIRROR
environment variable allows you to host engine files via a private server, AWS bucket or other cloud storage.
This can be useful if you have a custom OS that requires custom-built engines.
$PRISMA_ENGINES_MIRROR=https://my-aws-bucket