prisma/prisma

Custom engines

How to build and use a non-default Schema Engine binary or Wasm artifact during development. Sourced from CONTRIBUTING.md and AGENTS.md.

When you need this

You're developing a feature in prisma-engines and want to test it through the TypeScript stack
You want to build a Schema Engine from a specific prisma-engines branch to verify a fix
You're investigating a regression and need to bisect engine versions

Engine override mechanism

packages/fetch-engine/package.json accepts an enginesOverride field. Two flavors:

Branch override

{
  "enginesOverride": {
    "branch": "feat/column-comparison"
  }
}

The build script git pulls prisma/prisma-engines at that branch and builds the binaries from there. Slower (full Rust build) but doesn't require local engine work.

Folder override

{
  "enginesOverride": {
    "folder": "/home/john/dev/prisma/prisma-engines/target/release"
  }
}

Use already-built artifacts from a local checkout. Fastest if you already have a build.

After editing the override

pnpm install   # propagates the override to all packages that consume engines

pnpm check-engines-override (scripts/check-engines-override.ts) is the safety net that prevents shipping a release with an enginesOverride set. Run it before any release operation.

If your changes are in the Wasm modules (PSL parser or query compiler) rather than the Schema Engine binary, build them directly and file:-link them. Assuming $PRISMA_ENGINES_ROOT is the prisma-engines checkout:

# In prisma-engines:
make build-schema-wasm
make build-qc-wasm

# In prisma:
pnpm upgrade -r @prisma/prisma-schema-wasm@file:$PRISMA_ENGINES_ROOT/target/prisma-schema-wasm
pnpm upgrade -r @prisma/query-compiler-wasm@file:$PRISMA_ENGINES_ROOT/query-compiler/query-compiler-wasm/pkg
pnpm build

Build only what you need:

Schema Wasm only if your change is isolated to PSL/DMMF and you only need to run CLI/generator tests, not Client.
Query Compiler Wasm only if your change is in query planning and doesn't touch the schema or DMMF.
Both when in doubt — the cost of an extra build is less than the cost of debugging a partial one.

CI engine branch overrides

For PRs, you don't need to ship an enginesOverride. Instead, add /engine-branch <branchName> to the PR description and re-run the pipeline. The build-engine-branch.yml workflow builds engines from that branch on CI before any tests run.

Triggering panics

Useful for testing engine error paths without modifying engine code:

Variable	Triggered by
`FORCE_PANIC_SCHEMA_ENGINE=1`	`npx prisma migrate dev`
`FORCE_PANIC_PRISMA_SCHEMA=1`	`npx prisma format`
`FORCE_PANIC_GET_DMMF=1`	`npx prisma validate`
`FORCE_PANIC_GET_CONFIG=1`	`npx prisma validate`

Each forces a panic in the corresponding code path. Verifies that error rendering in @prisma/internals and @prisma/migrate handles hard failures.