diff --git a/content/200-orm/200-prisma-client/700-debugging-and-troubleshooting/140-debugging.mdx b/content/200-orm/200-prisma-client/700-debugging-and-troubleshooting/140-debugging.mdx index a219ebc384..bdb11684f5 100644 --- a/content/200-orm/200-prisma-client/700-debugging-and-troubleshooting/140-debugging.mdx +++ b/content/200-orm/200-prisma-client/700-debugging-and-troubleshooting/140-debugging.mdx @@ -4,7 +4,6 @@ metaTitle: 'Debugging (Reference)' metaDescription: 'This page explains how to enable debugging output for Prisma Client by setting the `DEBUG` environment variable.' --- - You can enable debugging output in Prisma Client and Prisma CLI via the [`DEBUG`](/orm/reference/environment-variables-reference#debug) environment variable. It accepts two namespaces to print debugging output: @@ -13,13 +12,11 @@ You can enable debugging output in Prisma Client and Prisma CLI via the [`DEBUG` - `prisma*`: Prints all debug messages from Prisma Client or CLI - `*`: Prints all debug messages - +:::info Prisma Client can be configured to log warnings, errors and information related to queries sent to the database. See [Configuring logging](/orm/prisma-client/observability-and-logging/logging) for more information. - - - +::: ## Setting the `DEBUG` environment variable diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index 8dd4fff307..31b6eb1914 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -377,13 +377,13 @@ generator client { | `--allow-no-models` | No | The `generate` command will generate Prisma Client without generating any models. | | `--watch` | No | The `generate` command will continue to watch the `schema.prisma` file and re-generate Prisma Client on file changes. | - +:::warning **Deprecation Warning** As of Prisma 5.2.0, `--data-proxy` and `--accelerate` are deprecated in favor of `--no-engine` as Prisma Client no longer requires an option to work with Prisma Accelerate. All options are available and work similarly, but we recommend `--no-engine` as it prevents an engine from being downloaded which will greatly impact the size of apps deployed to serverless and edge functions. - +::: #### Arguments @@ -675,32 +675,32 @@ For downloading engines - BINARY_DOWNLOAD_VERSION: For configuring the Query Engine Type - - PRISMA_CLI_QUERY_ENGINE_TYPE: - - PRISMA_CLIENT_ENGINE_TYPE: + - PRISMA_CLI_QUERY_ENGINE_TYPE: (Not supported in Prisma ORM v7) + - PRISMA_CLIENT_ENGINE_TYPE: (Not supported in Prisma ORM v7) For custom engines - - PRISMA_QUERY_ENGINE_BINARY: - - PRISMA_QUERY_ENGINE_LIBRARY: + - PRISMA_QUERY_ENGINE_BINARY: (Not supported in Prisma ORM v7) + - PRISMA_QUERY_ENGINE_LIBRARY: (Not supported in Prisma ORM v7) - PRISMA_SCHEMA_ENGINE_BINARY: - PRISMA_MIGRATION_ENGINE_BINARY: For the "postinstall" npm hook - - PRISMA_GENERATE_SKIP_AUTOINSTALL: - - PRISMA_SKIP_POSTINSTALL_GENERATE: - - PRISMA_GENERATE_IN_POSTINSTALL: + - PRISMA_GENERATE_SKIP_AUTOINSTALL: (Not supported in Prisma ORM v7) + - PRISMA_SKIP_POSTINSTALL_GENERATE: (Not supported in Prisma ORM v7) + - PRISMA_GENERATE_IN_POSTINSTALL: (Not supported in Prisma ORM v7) For "prisma generate" - - PRISMA_GENERATE_DATAPROXY: - - PRISMA_GENERATE_NO_ENGINE: + - PRISMA_GENERATE_DATAPROXY: (Not supported in Prisma ORM v7) + - PRISMA_GENERATE_NO_ENGINE: (Not supported in Prisma ORM v7) For Prisma Client - PRISMA_SHOW_ALL_TRACES: - - PRISMA_CLIENT_NO_RETRY (Binary engine only): + - PRISMA_CLIENT_NO_RETRY (Binary engine only): (Not supported in Prisma ORM v7) For Prisma Migrate - PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK: - - PRISMA_MIGRATE_SKIP_GENERATE: - - PRISMA_MIGRATE_SKIP_SEED: + - PRISMA_MIGRATE_SKIP_GENERATE: (Not supported in Prisma ORM v7) + - PRISMA_MIGRATE_SKIP_SEED: (Not supported in Prisma ORM v7) For Prisma Studio - BROWSER: @@ -815,17 +815,17 @@ npx prisma dev stop mydb* # stops all DBs starting with `mydb` The `db pull` command connects to your database and adds Prisma models to your Prisma schema that reflect the current database schema. - +:::warning **Warning**: The command will overwrite the current `schema.prisma` file with the new schema. Some manual changes or customization can be lost. Be sure to back up your current `schema.prisma` file (or commit your current state to version control to be able to revert any changes) before running `db pull` if it contains important modifications. - +::: - +:::info Introspection with the `db pull` command on the [MongoDB connector](/orm/overview/databases/mongodb) samples the data instead of reading a schema. - +::: #### Prerequisites @@ -1041,17 +1041,17 @@ prisma db seed ### `db execute` - +:::info The `db execute` command is Generally Available in versions 3.13.0 and later. If you're using a version between 3.9.0 and 3.13.0, it is available behind a `--preview-feature` CLI flag. - +::: - +:::warning This command is currently not supported on [MongoDB](/orm/overview/databases/mongodb). - +::: This command applies a SQL script to the database without interacting with the Prisma migrations table. The script takes two inputs: @@ -1117,12 +1117,12 @@ Other options: Prisma Migrate changed from Preview to Generally Available (GA) in 2.19.0. - +:::info **Does not apply for MongoDB**
Instead of `migrate dev` and related commands, [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) is used for [MongoDB](/orm/overview/databases/mongodb). - +::: ### `migrate dev` @@ -1136,11 +1136,11 @@ The `migrate dev` command: 1. Applies all unapplied migrations to the development database and updates the `_prisma_migrations` table 1. Triggers the generation of artifacts (for example, Prisma Client) - +:::warning This command is not supported on [MongoDB](/orm/overview/databases/mongodb). Use [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) instead. - +::: See also: @@ -1157,11 +1157,11 @@ See also: | `--name` / `-n` | No | Name the migration (e.g. `prisma migrate dev --name added_job_title`) | | | `--help` / `-h` | No | Displays the help message | | - +:::info If a [schema drift](/orm/prisma-migrate/understanding-prisma-migrate/shadow-database#detecting-schema-drift) is detected while running `prisma migrate dev` using `--create-only`, you will be prompted to reset your database. - +::: #### Arguments @@ -1195,11 +1195,11 @@ This command: 1. Applies all migrations 1. Runs seed scripts - +:::warning This command is not supported on [MongoDB](/orm/overview/databases/mongodb). Use [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) instead. - +::: #### Options @@ -1260,11 +1260,11 @@ The `migrate deploy` command applies all pending migrations, and creates the dat - Does **not** reset the database or generate artifacts - Does **not** rely on a shadow database - +:::warning This command is not supported on [MongoDB](/orm/overview/databases/mongodb). Use [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) instead. - +::: #### Options @@ -1290,11 +1290,11 @@ The `migrate resolve` command allows you to solve migration history issues in pr Note that this command can only be used with a failed migration. If you try to use it with a successful migration you will receive an error. - +:::warning This command is not supported on [MongoDB](/orm/overview/databases/mongodb). Use [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) instead. - +::: #### Options @@ -1326,11 +1326,11 @@ prisma migrate resolve --rolled-back 20201231000000_add_users_table The `prisma migrate status` command looks up the migrations in `./prisma/migrations/*` folder and the entries in the `_prisma_migrations` table and compiles information about the state of the migrations in your database. - +:::warning This command is not supported on [MongoDB](/orm/overview/databases/mongodb). Use [`db push`](/orm/prisma-migrate/workflows/prototyping-your-schema) instead. - +::: For example: diff --git a/content/200-orm/500-reference/300-environment-variables-reference.mdx b/content/200-orm/500-reference/300-environment-variables-reference.mdx index 407c6bf4fe..9bc8dcc2a2 100644 --- a/content/200-orm/500-reference/300-environment-variables-reference.mdx +++ b/content/200-orm/500-reference/300-environment-variables-reference.mdx @@ -6,12 +6,8 @@ sidebar_label: 'Environment variables' tocDepth: 3 --- - - This document describes different environment variables and their use cases. - - ## Prisma Client ### `DEBUG` @@ -63,10 +59,22 @@ See [Studio](/orm/reference/prisma-cli-reference#studio) documentation for more ### `PRISMA_GENERATE_SKIP_AUTOINSTALL` +:::danger Prisma v7 Deprecation + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_GENERATE_SKIP_AUTOINSTALL` can be set to a truthy value to skip the auto-install of `prisma` CLI and `@prisma/client` dependencies (if they are missing), if the `prisma-client-js` generator is defined in the Prisma Schema, when using the `prisma generate` command. ### `PRISMA_SKIP_POSTINSTALL_GENERATE` +:::danger Prisma v7 deprecation + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_SKIP_POSTINSTALL_GENERATE` can be set to a truthy value to skip the auto-generation of Prisma Client when its `postinstall` hook is triggered by a package manager. The `postinstall` hook of the `@prisma/client` package is triggered when the package is installed, or its version is updated. ### `PRISMA_DISABLE_WARNINGS` @@ -75,21 +83,29 @@ Disables all CLI warnings generated by `logger.warn`. ### `PRISMA_GENERATE_NO_ENGINE` - + + +:::danger Prisma v7 deprecation + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + +:::info This environment variable is available since version `5.2.0` - +::: `PRISMA_GENERATE_NO_ENGINE` can be set to a truthy value to generate a Prisma Client without an included [query engine](/orm/more/under-the-hood/engines) in order to reduce deployed application size when paired with [Prisma Accelerate](/accelerate). ### `PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK` - +:::info This environment variable is available since version `5.3.0` - +::: `PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK` can be set to a truthy value to disable the [advisory locking](/orm/prisma-migrate/workflows/development-and-production#advisory-locking) used by Prisma Migrate. This might be needed, depending on the database configuration, for example, for a Percona-XtraDB-Cluster or MariaDB Galera Cluster. @@ -127,6 +143,12 @@ HTTPS_PROXY=https://proxy.example.com #### `PRISMA_CLI_QUERY_ENGINE_TYPE` +:::danger[Removed in Prisma v7] + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_CLI_QUERY_ENGINE_TYPE` is used to [define the query engine type Prisma CLI downloads and uses](/orm/more/under-the-hood/engines#configuring-the-query-engine). Defaults to `library`, but can be set to `binary`: ```env @@ -135,6 +157,12 @@ PRISMA_CLI_QUERY_ENGINE_TYPE=binary #### `PRISMA_CLIENT_ENGINE_TYPE` +:::danger[Removed in Prisma v7] + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_CLIENT_ENGINE_TYPE` is used to [define the query engine type Prisma Client downloads and uses](/orm/more/under-the-hood/engines#configuring-the-query-engine). Defaults to `library`, but can be set to `binary`: ```env @@ -161,11 +189,11 @@ Note: This environment variable used to be available as `PRISMA_BINARIES_MIRROR` #### `PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING` - +:::info This environment variable is available since version `4.16.0` - +::: `PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING` can be can be set to a truthy value to ignore problems around downloading & verifying the integrity (via a checksum file) of the Prisma ORM engines. This is particularly useful when deploying to an offline system environment where the checksum file cannot be downloaded. @@ -182,6 +210,12 @@ By default, all engine files are downloaded when you install Prisma CLI, copied #### `PRISMA_QUERY_ENGINE_BINARY` +:::danger Prisma v7 Deprecation + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_QUERY_ENGINE_BINARY` is used to set a custom location for your own query engine binary. ```env @@ -196,6 +230,12 @@ Note: This can only have an effect if the engine type of CLI or Client are set t #### `PRISMA_QUERY_ENGINE_LIBRARY` +:::danger Prisma v7 Deprecation + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_QUERY_ENGINE_LIBRARY` is used to set a custom location for your own query engine library. ```env @@ -218,11 +258,11 @@ PRISMA_SCHEMA_ENGINE_BINARY=custom/my-schema-engine-unix #### `PRISMA_MIGRATION_ENGINE_BINARY` - +:::warning **Deprecated**: `PRISMA_MIGRATION_ENGINE_BINARY` variable is deprecated in [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) because Migration engine was renamed to Schema Engine. - +::: `PRISMA_MIGRATION_ENGINE_BINARY` is used to set a custom location for your own migration engine binary. @@ -232,25 +272,31 @@ PRISMA_MIGRATION_ENGINE_BINARY=custom/my-migration-engine-unix #### `PRISMA_INTROSPECTION_ENGINE_BINARY` +:::danger[Removed in Prisma v7] + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_INTROSPECTION_ENGINE_BINARY` is used to set a custom location for your own introspection engine binary. ```env PRISMA_INTROSPECTION_ENGINE_BINARY=custom/my-introspection-engine-unix ``` - +:::warning The Introspection Engine is served by the Migration Engine from [4.9.0](https://github.com/prisma/prisma/releases/tag/4.9.0). Therefore, the `PRISMA_INTROSPECTION_ENGINE` environment variable will not be used. - +::: #### `PRISMA_FMT_BINARY` - +:::danger This functionality has been removed in Prisma CLI version 4.10.0. It only works in earlier versions. - +::: `PRISMA_FMT_BINARY` is used to set a custom location for your own format engine binary. @@ -258,16 +304,22 @@ This functionality has been removed in Prisma CLI version 4.10.0. It only works PRISMA_FMT_BINARY=custom/my-custom-format-engine-unix ``` - +:::warning The `PRISMA_FMT_BINARY` variable is used in versions [4.2.0](https://github.com/prisma/prisma/releases/tag/4.2.0) or lower. - +::: ### CLI Binary Targets #### `PRISMA_CLI_BINARY_TARGETS` +:::danger Prisma v7 Deprecation + +This environment variable is only supported in Prisma 6.19 and earlier. It will not work in Prisma v7. + +::: + `PRISMA_CLI_BINARY_TARGETS` can be used to specify one or more binary targets that Prisma CLI will download during installation (so it must be provided during `npm install` of Prisma CLI and does not affect runtime of Prisma CLI or Prisma Client). Use `PRISMA_CLI_BINARY_TARGETS` if you 1) deploy to a specific platform via an upload of a local project that includes dependencies, and 2) your local environment is different from the target (e.g. AWS Lambda with Node.js 20+ is `rhel-openssl-3.0.x`, and your local environment might be macOS arm64 `darwin-arm64`). Using the `PRISMA_CLI_BINARY_TARGETS` environment variable ensures that the target engine files are also downloaded. @@ -278,4 +330,8 @@ PRISMA_CLI_BINARY_TARGETS=darwin-arm64,rhel-openssl-3.0.x npm install This is the Prisma CLI equivalent for the [`binaryTargets` property of the `generator` block](/orm/prisma-schema/overview/generators#binary-targets), which enables you to define the same setting for Prisma Client. -> **Note**: For Node.js versions earlier than 20, the openssl version was 1.0.x instead of 3.0.x. This is most obvious in AWS Lambda deployments, where the binary target would be `rhel-openssl-1.0.x` instead of `rhel-openssl-3.0.x`. +:::info[Note] + +For Node.js versions earlier than 20, the openssl version was 1.0.x instead of 3.0.x. This is most obvious in AWS Lambda deployments, where the binary target would be `rhel-openssl-1.0.x` instead of `rhel-openssl-3.0.x`. + +::: diff --git a/content/200-orm/800-more/100-under-the-hood/100-engines.mdx b/content/200-orm/800-more/100-under-the-hood/100-engines.mdx index 78a8e65d4e..78d23be5a0 100644 --- a/content/200-orm/800-more/100-under-the-hood/100-engines.mdx +++ b/content/200-orm/800-more/100-under-the-hood/100-engines.mdx @@ -1,73 +1,96 @@ --- title: 'Engines' metaTitle: 'Engines' -metaDescription: "Prisma's query engine manages the communication with the database when using Prisma Client. Learn how it works on this page." +metaDescription: "Prisma's query engine manages the communication with the database when using Prisma ORM. Learn how it works on this page." --- -From a technical perspective, Prisma Client consists of three major components: +:::warning[Prisma ORM v7 is Rust binary-free by default] -- JavaScript client library -- TypeScript type definitions -- A query engine +As of **Prisma ORM v7**, Prisma ORM runs without Rust engines by default. This means: -All of these components are located in the [generated `.prisma/client` folder](/orm/prisma-client/setup-and-configuration/generating-prisma-client#the-prismaclient-npm-package) after you ran `prisma generate`. +- No Rust binary-based query engine binary is included in your generated code +- Queries are compiled to SQL using a TypeScript-based query compiler +- [Driver adapters](/orm/overview/databases/database-drivers#driver-adapters) are required for database connectivity +- The generated code is smaller and more portable across different JavaScript environments -This page covers relevant technical details about the query engine. +This page documents the legacy Rust-based engine architecture. For the modern Rust-free approach (default in v7), see [Prisma ORM without Rust engines](/orm/prisma-client/setup-and-configuration/no-rust-engine). -:::note +::: -As of [v6.16.0](https://pris.ly/release/6.16.0), Prisma ORM can be used without Rust engines in production applications. Learn more [here](/orm/prisma-client/setup-and-configuration/no-rust-engine). +:::info[Default generator in Prisma ORM v7] -**When enabled, your Prisma Client will be generated without a Rust-based query engine binary**: +The `prisma-client` generator is now the default in Prisma ORM v7. It generates TypeScript code into a custom directory you specify (via the `output` field). -```prisma -generator client { - provider = "prisma-client-js" // or "prisma-client" - output = "../src/generated/prisma" - engineType = "client" // no Rust engine -} -``` +Learn more about the [`prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client). -Note that [driver adapters](/orm/overview/databases/database-drivers#driver-adapters) are required if you want to use Prisma ORM without Rust engines. +::: -You can [read about the performance and DX improvements](https://www.prisma.io/blog/prisma-orm-without-rust-latest-performance-benchmarks) of this change on our blog. +From a technical perspective, when using **Rust-based engines** (legacy approach), Prisma Client consists of three major components: -::: +- JavaScript client library +- TypeScript type definitions +- A query engine (Rust-based) + +All of these components are located in the generated output folder after you run `prisma generate`. + +This page covers relevant technical details about the **Rust-based query engine architecture**, which is now optional and primarily used for: +- Legacy `prisma-client-js` generator users +- Users who explicitly set `engineType = "library"` or `engineType = "binary"` with the `prisma-client` generator ## Prisma engines +:::warning + +This section describes the **legacy Rust-based engine architecture**. In Prisma ORM v7, the default architecture uses a TypeScript-based query compiler without Rust engines. + +::: + At the core of each module, there typically is a [Prisma engine](https://github.com/prisma/prisma-engines) that implements the core set of functionality. Engines are implemented in [Rust](https://www.rust-lang.org/) 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](/orm/more/under-the-hood/engines) in order to read and write data in a database: +As an example, when using Rust-based engines, Prisma Client connects to the query engine in order to read and write data in a database: ![Prisma engine](./typical-flow-query-engine-at-runtime.png) ### 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](/orm/more/under-the-hood/engines) is also copied to the generated Prisma Client when you call `prisma generate`. +:::warning + +This section applies **only to Rust-based engines**. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries. + +::: + +When using Rust-based engines, 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](/orm/more/under-the-hood/engines) is also copied to the generated Prisma Client when you call `prisma generate`. + You might want to use a [custom library or binary](https://github.com/prisma/prisma-engines) 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: +Use the following environment variables to specify custom locations for your Rust engine binaries: -- [`PRISMA_QUERY_ENGINE_LIBRARY`](/orm/reference/environment-variables-reference#prisma_query_engine_library) (Query engine, library) -- [`PRISMA_QUERY_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_query_engine_binary) (Query engine, binary) +- [`PRISMA_QUERY_ENGINE_LIBRARY`](/orm/reference/environment-variables-reference#prisma_query_engine_library) (Query engine, library) — **Not supported in Prisma ORM v7** +- [`PRISMA_QUERY_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_query_engine_binary) (Query engine, binary) — **Not supported in Prisma ORM v7** - [`PRISMA_SCHEMA_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_schema_engine_binary) (Schema engine) - [`PRISMA_MIGRATION_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_migration_engine_binary) (Migration engine) -- [`PRISMA_INTROSPECTION_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_introspection_engine_binary) (Introspection engine) +- [`PRISMA_INTROSPECTION_ENGINE_BINARY`](/orm/reference/environment-variables-reference#prisma_introspection_engine_binary) (Introspection engine) — **Not supported in Prisma ORM v7** + +:::warning - +**Prisma ORM v7 changes:** -- `PRISMA_MIGRATION_ENGINE_BINARY` variable is deprecated in [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0). -- The Introspection Engine is served by the Migration Engine from [4.9.0](https://github.com/prisma/prisma/releases/tag/4.9.0). Therefore, the `PRISMA_INTROSPECTION_ENGINE` environment variable will not be used. +- `PRISMA_QUERY_ENGINE_LIBRARY` and `PRISMA_QUERY_ENGINE_BINARY` are not supported in Prisma ORM v7. +- `PRISMA_INTROSPECTION_ENGINE_BINARY` is not supported in Prisma ORM v7. + +**Earlier deprecations:** + +- `PRISMA_MIGRATION_ENGINE_BINARY` variable is deprecated in [5.0.0](https://github.com/prisma/prisma/releases/tag/5.0.0) because the Migration engine was renamed to Schema Engine. +- The Introspection Engine is served by the Schema Engine from [4.9.0](https://github.com/prisma/prisma/releases/tag/4.9.0). Therefore, the `PRISMA_INTROSPECTION_ENGINE` environment variable will not be used. - The `PRISMA_FMT_BINARY` variable is used in versions [4.2.0](https://github.com/prisma/prisma/releases/tag/4.2.0) or lower. - +::: #### Setting the environment variable @@ -157,6 +180,12 @@ Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2dd ### Hosting engines +:::warning + +This section applies **only to Rust-based engines**. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries. + +::: + The [`PRISMA_ENGINES_MIRROR`](/orm/reference/environment-variables-reference#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. @@ -166,6 +195,12 @@ PRISMA_ENGINES_MIRROR=https://my-aws-bucket ## The query engine file +:::warning + +This section applies **only to Rust-based engines**. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries. + +::: + The **query engine file** is different for each operating system. It is named `query-engine-PLATFORM` or `libquery_engine-PLATFORM` where `PLATFORM` corresponds to the name of a compile target. Query engine file extensions depend on the platform as well. As an example, if the query engine must run on a [Darwin]() operating system such as macOS Intel, it is called `libquery_engine-darwin.dylib.node` or `query-engine-darwin`. You can find an overview of all supported platforms [here](/orm/reference/prisma-schema-reference#binarytargets-options). The query engine file is downloaded into the `runtime` directory of the generated Prisma Client when `prisma generate` is called. @@ -174,7 +209,13 @@ Note that the query engine is implemented in Rust. The source code is located in ## The query engine at runtime -By default, Prisma Client loads the query engine as a [Node-API library](https://nodejs.org/api/n-api.html). You can alternatively [configure Prisma to use the query engine compiled as an executable binary](#configuring-the-query-engine), which is run as a sidecar process alongside your application. +:::warning + +This section applies **only to Rust-based engines**. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries. + +::: + +When using Rust-based engines, Prisma Client loads the query engine as a [Node-API library](https://nodejs.org/api/n-api.html) by default. You can alternatively [configure Prisma to use the query engine compiled as an executable binary](#configuring-the-query-engine), which is run as a sidecar process alongside your application. The Node-API library approach is recommended since it reduces the communication overhead between Prisma Client and the query engine. ![Diagram showing the query engine and Node.js at runtime](./query-engine-node-js-at-runtime.png) @@ -201,7 +242,13 @@ The following diagram depicts a "typical flow": ## Responsibilities of the query engine -The query engine has the following responsibilities in an application that uses Prisma Client: +:::warning + +This section applies **only to Rust-based engines**. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries. + +::: + +The Rust-based 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 @@ -211,7 +258,13 @@ The query engine has the following responsibilities in an application that uses ## Debugging the query engine -You can access the logs of the query engine by setting the [`DEBUG`](/orm/prisma-client/debugging-and-troubleshooting/debugging) environment variable to `engine`: +:::warning + +This section applies only to Rust-based engines. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries. + +::: + +You can access the logs of the Rust-based query engine by setting the [`DEBUG`](/orm/prisma-client/debugging-and-troubleshooting/debugging) environment variable to `engine`: ```terminal export DEBUG="engine" @@ -229,26 +282,47 @@ Learn more about [Debugging](/orm/prisma-client/debugging-and-troubleshooting/de ## Configuring the query engine +:::warning + +The configuration options in this section apply **only to Rust-based engines** used in Prisma ORM v6.19 and earlier. Prisma ORM v7 uses the TypeScript-based query compiler by default and does not use these Rust engine configurations. + +::: + ### Defining the query engine type for Prisma Client -[As described above](#the-query-engine-at-runtime) the default query engine is a Node-API library that is loaded into Prisma Client, but there is also an alternative implementation as an executable binary that runs in its own process. You can configure the query engine type by providing the `engineType` property to the Prisma Client `generator`: +When using Rust-based engines, you can choose between a Node-API library or an executable binary. Configure the query engine type by providing the `engineType` property to the Prisma Client `generator`: ```prisma generator client { - provider = "prisma-client-js" - engineType = "binary" + provider = "prisma-client-js" // or "prisma-client" + engineType = "binary" // or "library" for Rust-based engines } ``` -Valid values for `engineType` are `binary` and `library`. You can also use the environment variable [`PRISMA_CLIENT_ENGINE_TYPE`](/orm/reference/environment-variables-reference#prisma_client_engine_type) instead. +Valid values for `engineType` are: +- `binary` - Executable binary that runs as a sidecar process (Rust-based) +- `library` - Node-API library loaded into Prisma Client (Rust-based, default for v6 and earlier) + +:::warning + +The environment variable `PRISMA_CLIENT_ENGINE_TYPE` is not supported in Prisma ORM v7 because Prisma Client now defaults to the TypeScript-based query compiler without Rust engine binaries. See [Prisma ORM without Rust engines](/orm/prisma-client/setup-and-configuration/no-rust-engine) for more information. - +::: + +:::info[Historical context] - Until Prisma 3.x the default and only engine type available was `binary`, so there was no way to configure the engine type to be used by Prisma Client and Prisma CLI. - From versions [2.20.0](https://github.com/prisma/prisma/releases/2.20.0) to 3.x the `library` engine type was available and used by default by [activating the preview feature flag](/orm/reference/preview-features/client-preview-features#enabling-a-prisma-client-preview-feature) "`nApi`" or using the `PRISMA_FORCE_NAPI=true` environment variable. +- As of Prisma ORM v7, the TypeScript-based query compiler (no Rust binaries) is the default and `engineType` does not need to be set. - +::: ### Defining the query engine type for Prisma CLI -Prisma CLI also uses its own query engine for its own needs. You can configure it to use the binary version of the query engine by defining the environment variable [`PRISMA_CLI_QUERY_ENGINE_TYPE=binary`](/orm/reference/environment-variables-reference#prisma_cli_query_engine_type). +When using Rust-based engines, Prisma CLI also uses its own query engine. You can configure it to use the binary version of the query engine by defining the environment variable [`PRISMA_CLI_QUERY_ENGINE_TYPE=binary`](/orm/reference/environment-variables-reference#prisma_cli_query_engine_type). + +:::warning + +The environment variable `PRISMA_CLI_QUERY_ENGINE_TYPE` is not supported in Prisma ORM v7 because Prisma CLI now defaults to the TypeScript-based query compiler without Rust engine binaries. See [Prisma ORM without Rust engines](/orm/prisma-client/setup-and-configuration/no-rust-engine) for more information. + +:::