Overview

From a technical perspective, Prisma Client consists of three major components:

  • JavaScript client library
  • TypeScript type definitions
  • A query engine (in the form of binary file)

All of these components are located in the generated .prisma/client folder after you ran prisma generate.

This page covers relevant technical details about the query engine.

The query engine binary file

The query engine binary file is called query-engine-PLATFORM where PLATFORM corresponds to the name of a compile target. For example, if the query engine must run on a Darwin operating system (e.g. Mac OS), it's called query-engine-darwin. You can find an overview of all supported platforms here.

The query engine binary file is downloaded into the runtime directory of node_modules/@prisma/client when prisma generate is called.

Note that the query engine is implemented in Rust. The source code is located in the prisma-engines repository.

The query engine at runtime

The query engine is running as a separate process on the same machine where the Node.js/TypeScript application is running.

The query engine process is started when the $connect() method is called on your PrismaClient instance. Once the process is started, the query engine creates a connection pool and manages the physical connections to the database. From that point onwards, Prisma Client is ready to send queries to the database (e.g. findOne, findMany, create, ...).

The query engine process is stopped and the database connections are closed when $disconnect() is invoked.

The following diagram depicts a "typical flow":

  1. $connect() is invoked on Prisma Client
  2. The query engine process is started
  3. The query engine establishes connections to the database and creates connection pool
  4. Prisma Client is now ready to send queries to the database
  5. Prisma Client sends a findMany() query to the query engine
  6. The query engine translates the query into SQL and sends it to the database
  7. The query engine receives the SQL response from the database
  8. The query engine returns the result as plain old JavaScipt objects to Prisma Client
  9. $disconnect() is invoked on Prisma Client
  10. The query engine closes the database connections
  11. The query engine process is stopped

Responsibilities of the query engine

The query engine has the following responsibilities in an application that uses Prisma Client:

  • manage physical database connections in connection pool
  • receive incoming queries from the Prisma Client Node.js process
  • generate SQL queries
  • send SQL queries to the database
  • process responses from the database and send them back to Prisma Client

Debugging the query engine

You can access the logs of the query engine by setting the DEBUG environment variable to engine:

$export DEBUG="engine"

You can also get more visibility into the SQL queries that are generated by the query engine by setting the query log level in Prisma Client:

1const prisma = new PrismaClient({
2 log: ['query'],
3})

Learn more in the Debugging and Logging pages of the docs.

Edit this page on Github