Enabling Node-API libraries: Remove `nApi` preview feature flag and make Node-API libraries the new default, provide escape hatch to old behavior

We added the preview feature flag nApi in release 2.20.0 to let users try out the new Node-API library that could potentially replace the existing Rust binary. Results were promising, and the few bugs or regressions we found we could fortunately fix, so we are moving forward with figuring out how to enable this library for all users by default.

But we also need to give everyone an option to opt-out of the new behavior and keep using the existing binary as it is in production right now if they need it. Reasons for that can be special use cases, unwanted new or changed behavior, undetected bugs on our side and so on.

Enabling Node-API library by default

During the Preview phase of the functionality, users could opt in to the feature by either adding the nApi preview feature flag to the previewFeatures list of the generator block of Prisma Client, or by setting an environment variable PRISMA_FORCE_NAPI=true in their system environment to also enable the Node-API library for Prisma Client.

Now when a user just installs and uses Prisma, they directly get the Node-API library instead of the binary everywhere. The preview feature flag nApi and existing environment variable PRSMA_FORCE_NAPI are removed and not supported anymore.

The escape hatch back to the binary

So with the Node-API library enabled, everyone will get the Node-API library for both Prisma Client and Prisma CLI by default. But as laid out above, we need an escape hatch that allows to switch back to the binary as well. This is not trivial:

• To understand if a preview feature flag in the Prisma schema file is enabled for the CLI to download the correct engine file, we actually already need an engine that can parse the schema and return a representation of it that includes “nApi is one of the enabled preview features”.
• This can be necessary as early as when the user runs npm install, as Prisma triggers a postinstall hook that runs prisma generate to generate a Prisma Client ready to be used as early as possible.
• This is a chicken or egg problem, that we got around in the preview phase by only using the Node-API library in the CLI when the environment variable was set (and not via the preview feature flag in the Prisma Schema). This is confusing and hard to document. For the escape hatch we need to do better here.
• The escape hatch also has to be present in the generated Client, which might not have access to many of the places that could be used for this configuration (A generated Prisma Client could be distributed via Npm, where only the @prisma/client and .prisma/client are included, or just copied between projects that do not have any of the other Prisma files present).

This means the configuration for the escape hatch has to be considered carefully.

Options

There are multiple options that we can consider (ordered by how “fixed” they are): (Note that we make a suggestion on which of these options should be implemented below)

Client and CLI

1. Environment variable - An environment variable is a simple global configuration option that can be read from both CLI and Client. It can be different per system though, and does not have the best developer experience as setting them is different per deployment platform, operating system and so on.

2. PrismaClient constructor - The constructor PrismaClient in the code when using Prisma Client is used by us as a place to override the datasource’s url property on runtime. It by definition only covers the client, after everything (both CLI and Client) were already installed and generated.

3. schema.prisma file - The Prisma Schema file is another place where we can put configuration, like the previewFeatures list in the generator block of Prisma Clients.

   It has a few disadvantages:

   • There is no top level configuration in Prisma Schema yet - only blocks like generator, datasource or model etc. can take properties. This configuration for the escape hatch does not make much sense scoped to any of these, but would need to be global.
   • We do not actually have a parser for the schema file CLI or Client side - only via talking to an existing engine binary or library they can actually find out about the configuration included in that file.

4. package.json file - The project’s package.json file is already used to be able to customize the location of the schema.prisma file via a schema entry in the prisma object, both for the CLI and Client. The same location and functionality can be used for the escape hatch:

   "prisma": {
     "foo": "bar"
   }
   

5. Configuration file for Prisma - If there was an explicit configuration file for Prisma outside of schema.prisma or package.json, that could also be used to adopt this configuration. But of course, it adds a lot of additional complexity that is hopefully not necessary in the context of this project.

Generated Prisma Client

• For the generated Client (which includes the TypeScript types) there is only 1 option: Similar to how it includes a copy of the schema.prisma file (.prisma/client/schema.prisma), it also needs to include the buildtime (when prisma generate is run) value of the escape hatch. The obvious choice is a property in the Prisma Client generator: queryEngineType = 'napi' | 'binary'. To be able to override this on runtime, the generated Client will also listen to the environment variable described above.
  • Note: This is not a generator property to be documented publicly

Suggestions

We suggest as the escape hatch we implement options 1) Environment variable and option 4) package.json → prisma object:

• In package.json:

  "prisma": {
    "queryEngineType": "binary" // (vs. default `node-api`)
  }
  

• Environment variable: PRISMA_QUERY_ENGINE_TYPE=binary (vs. default node-api)

  • As usual the environment variable can be used to override any other choice made via other configuration options.

We chose these as they are available, proven to work, and fulfill the demands we have for the escape hatch configuration. (Options 2 and 3 are to late in the process, and option 5 is far to big to introduce for this configuration.)

[pantharshit00]

Follow: https://github.com/prisma/prisma/issues/8731

[pantharshit00]

@kripod Nope, nApi hasn’t left preview yet. That might happen next release but we still have some work remaining to do.