Building Prisma Engines

Build instructions and prerequisites for Prisma Engines development

Prerequisites

Before building Prisma Engines, ensure you have the following installed:

1. Install Rust Toolchain

   Install the latest stable version of Rust. You can get the toolchain at rustup or use your package manager.

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
2. Linux: Install OpenSSL

   On Linux systems, OpenSSL is required:

   # Ubuntu/Debian
   sudo apt-get install libssl-dev pkg-config
   
   # Fedora/RHEL
   sudo dnf install openssl-devel
   
3. Install direnv

   Install direnv to automatically load environment variables:

   # macOS
   brew install direnv
   
   # Linux
   # Follow instructions at https://direnv.net/docs/installation.html
   

   Make sure direnv is hooked into your shell.

4. Allow direnv in Repository

   Navigate to the repository root and allow direnv:

   cd /path/to/prisma-engines
   direnv allow
   

   Alternatively, you can manually load the environment variables defined in ./.envrc, but using direnv is recommended.

5. Optional: Install Node.js and pnpm

   Required for building driver adapters:

   • Node.js ≥ 20
   • pnpm package manager

   # Install Node.js 20+ using nvm
   nvm install 20
   nvm use 20
   
   # Install pnpm
   npm install -g pnpm
   

Environment Setup

The repository uses .envrc to configure essential environment variables:

export WORKSPACE_ROOT=$(pwd)
export RUST_LOG_FORMAT=devel
export RUST_LOG=info

You can create a .envrc.local file (gitignored) for local overrides.

Optional: Nix Users

The repository includes a shell.nix file for Nix users. If you have Nix installed and direnv configured, all dependencies will be automatically set up.

To disable Nix in environments where it’s pre-installed (e.g., Gitpod):

export DISABLE_NIX=1

Building the Engines

Build All Engines (Debug Mode)

To build all engines in debug mode:

cargo build

Binaries will be located in target/debug/:

Component	Binary Path
Schema Engine	./target/debug/schema-engine
Prisma Format	./target/debug/prisma-fmt

Build All Engines (Release Mode)

For optimized production binaries:

cargo build --release
# or
make release

Release binaries will be in target/release/.

Build Specific Components

Schema Engine

cargo build -p schema-engine-cli

cargo build -p prisma-fmt

make build-qc-wasm

make build-se-wasm

Build Query Compiler Wasm

The query compiler is a library crate that compiles to Wasm for the JavaScript runtime:

Fast Build

make build-qc-wasm-fast

make build-qc-wasm-small

make build-qc-wasm

Output location: query-compiler/query-compiler-wasm/pkg/

Build Driver Adapters

Driver adapters enable the query compiler to work with JavaScript database drivers:

1. Ensure prisma/prisma Repository

   The driver adapters build process requires the main Prisma repository as a sibling:

   cd ..
   git clone https://github.com/prisma/prisma.git
   cd prisma-engines
   
2. Build Driver Adapters Kit

   Query Compiler Adapters

   make build-driver-adapters-kit-qc
   

   make build-driver-adapters-kit
   

Build Targets Reference

Makefile Targets

Target	Description
make build	Build all engines (debug)
make release	Build all engines (release)
make build-qc-wasm	Build query compiler Wasm (fast + small)
make build-qc-wasm-fast	Build query compiler Wasm (fast variant)
make build-qc-wasm-small	Build query compiler Wasm (size-optimized)
make build-se-wasm	Build schema engine Wasm
make build-schema-wasm	Build Prisma schema Wasm package
make build-driver-adapters-kit	Build driver adapters (full)
make build-driver-adapters-kit-qc	Build driver adapters for query compiler
make pedantic	Run formatting and clippy checks (CI mode)
make clean	Clean all build artifacts

Clean Build Artifacts

Clean Everything

make clean

make clean-qc-wasm
make clean-se-wasm
make clean-cargo

Code Quality

Format Code

cargo fmt

Run Linter (Clippy)

cargo clippy --all-features --all-targets -- -Dwarnings

Pedantic CI Check

Emulate the CI compilation checks locally:

make pedantic

This runs:

1. cargo fmt -- --check (formatting validation)
2. cargo clippy --all-features --all-targets -Dwarnings (lint checks)
3. Additional Wasm target checks

Fix compiler and clippy diagnostics before addressing formatting issues.

Optimizing Build Performance

Parallel rust-analyzer Builds

When rust-analyzer runs cargo check, it locks the build directory. To avoid this:

1. Open VSCode settings
2. Search for “Check on Save: Extra Args”
3. Add a custom target directory:
   --target-dir:/tmp/rust-analyzer-check
   

Using LLD Linker (Linux)

The .envrc automatically configures the faster LLD linker on Linux if available:

# Install LLD
sudo apt-get install lld  # Ubuntu/Debian
sudo dnf install lld      # Fedora/RHEL

Troubleshooting

OpenSSL Not Found (Linux)

If you encounter OpenSSL linking errors:

sudo apt-get install libssl-dev pkg-config

direnv Not Loading

Ensure direnv is properly hooked in your shell config:

# For bash, add to ~/.bashrc:
eval "$(direnv hook bash)"

# For zsh, add to ~/.zshrc:
eval "$(direnv hook zsh)"

Wasm Build Fails

Ensure the Wasm target is installed:

rustup target add wasm32-unknown-unknown

Next Steps

Once you’ve successfully built the engines:

• Learn about testing
• Explore debugging techniques
• Review contribution guidelines