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.
Modules and interfaces
The tools in the Prisma toolkit are built with respect to two dimensions:
- Module: A set of functionality that's offered by Prisma
- Interface: A way to use the functionality of a module
The following illustration gives an overview of the tools that exist (or are planned) in the Prisma toolkit:
Modules
Prisma provides a number of features which are implemented in the form of modules. Here is an overview of the modules Prisma provides:
- Query: Send queries to your database
- Migrate: Perform schema migrations in your database
- Introspect: Read a database schema and translate into Prisma data model
- Schema: Construct and modify a Prisma schema file
- Generate: Generate clients for Prisma data sources
Interface
Interfaces offer a way to actually use the functionality of a module. The module-interface-matrix above shows four different levels of interfaces (from bottom to top):
- Engines Implements the core functionality consumed by the higher-level interfaces
- Library: A way to programmatically use the functionality of a module
- CLI: A way to use the functionality of a module on the command line
- GUI: A way to visually use the functionality of a module
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 binaries
By default, all binaries are automatically downloaded into the node_modules/@prisma/cli folder when you install or update @prisma/cli. You might want to use a custom binary file if:
- Automated download of binaries is not possible.
- You have created your own engine binary (for testing, or for an OS that is not officially supported).
Use the following environment variables to specify custom locations for your binaries:
PRISMA_QUERY_ENGINE_BINARY(Query engine)PRISMA_MIGRATION_ENGINE_BINARY(Migration engine)PRISMA_INTROSPECTION_ENGINE_BINARY(Introspection engine)PRISMA_FMT_BINARY(fornpx prisma format)
The prisma/.env file
To set an environment variable in the prisma/.env file:
Add the environment variable to the
prisma/.envfile:Unix, MacOSWindowsPRISMA_QUERY_ENGINE_BINARY=custom/path/my-query-engine-binaryRun the following command to output the paths to all binaries:
$npx prisma -vThe output shows that the query engine path comes from the
PRISMA_QUERY_ENGINE_BINARYenvironment variable:Unix, MacOSWindowsCurrent platform : darwinQuery Engine : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /custom/my-query-engine-windows)Migration Engine : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/migration-engine-windows)Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/introspection-engine-windows)Format Binary : prisma-fmt d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/prisma-fmt-windows)
Note: It is possible to use an
.envfile in a location outside theprismafolder.
Global environment variable
To set the an environment variable globally (in this example, PRISMA_QUERY_ENGINE_BINARY):
Run the following command to set the environment variable:
Unix, MacOSWindows$export PRISMA_QUERY_ENGINE_BINARY=/custom/my-query-engine-unixRun the following command to output the paths to all binaries:
$npx prisma -vThe output shows that the query engine path comes from the
PRISMA_QUERY_ENGINE_BINARYenvironment variable:Unix, MacOSWindowsCurrent platform : darwinQuery Engine : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /custom/my-query-engine-windows)Migration Engine : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/migration-engine-windows)Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/introspection-engine-windows)Format Binary : prisma-fmt d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/prisma-fmt-windows)
