This repository contains a collection of engines that power the core stack for Prisma, most prominently Prisma Client and Prisma Migrate.
The engines and their respective binary crates are:
- Query engine:
query-engine
- Migration engine:
migration-engine
- Introspection engine:
introspection-engine
- Prisma Format:
prisma-fmt
Prerequisites:
- Installed the stable Rust toolchain, at least version 1.48.0. You can get the toolchain at rustup or the package manager of your choice.
- Linux only: OpenSSL is required to be installed.
- Installed direnv, then
direnv allow
on the repository root.- Alternatively: Load the defined environment in
./.envrc
manually in your shell.
- Alternatively: Load the defined environment in
How to build:
To build all engines, simply execute cargo build
on the repository root. This
builds non-production debug binaries. If you want to build the optimized
binaries in release mode, the command is cargo build --release
.
Depending on how you invoked cargo
in the previous step, you can find the
compiled binaries inside the repository root in the target/debug
(without
--release
) or target/release
directories (with --release
):
Prisma Component | Path to Binary |
---|---|
Query Engine | ./target/[debug|release]/query-engine |
Migration Engine | ./target/[debug|release]/migration-engine |
Introspection Engine | ./target/[debug|release]/introspection-engine |
Prisma Format | ./target/[debug|release]/prisma-fmt |
The Query Engine can be run as a graphql server without using the Prisma Client. If using it on production please be aware the api and the query language can change any time. There is no guaranteed API stability.
Notable environment flags:
RUST_LOG_FORMAT=(devel|json)
sets the log format. By default outputsjson
.PRISMA_DML_PATH=[path_to_datamodel_file]
should point to the datamodel file location. This orPRISMA_DML
is required for the Query Engine to run.PRISMA_DML=[base64_encoded_datamodel]
an alternative way to provide a datamodel for the server.RUST_BACKTRACE=(0|1)
if set to 1, the error backtraces will be printed to the STDERR.LOG_QUERIES=[anything]
if set, the SQL queries will be written to theINFO
log. Needs the right log level enabled to be seen from the terminal.RUST_LOG=[filter]
sets the filter for the logger. Can be eithertrace
,debug
,info
,warning
orerror
, that will output ALL logs from every crate from that level. The.envrc
in this repo shows how to log different parts of the system in a more granular way.
Starting the Query Engine:
The engine can be started either with using the cargo
build tool, or
pre-building a binary and running it directly. If using cargo
, replace
whatever command that starts with ./query-engine
with cargo run --bin query-engine --
.
Help
> ./target/release/query-engine --help
query-engine d6f9915c25a2ae6eb793a3a18f87e576fb82e9da
USAGE:
query-engine [FLAGS] [OPTIONS] [SUBCOMMAND]
FLAGS:
--enable-raw-queries Enables raw SQL queries with executeRaw/queryRaw mutation
-h, --help Prints help information
--legacy Switches query schema generation to Prisma 1 compatible mode
-V, --version Prints version information
OPTIONS:
--host <host> The hostname or IP the query engine should bind to [default: 127.0.0.1]
-p, --port <port> The port the query engine should bind to [env: PORT=] [default: 4466]
SUBCOMMANDS:
cli Doesn't start a server, but allows running specific commands against Prisma
help Prints this message or the help of the given subcommand(s)
> ./target/release/query-engine cli --help
Doesn't start a server, but allows running specific commands against Prisma
USAGE:
query-engine cli <SUBCOMMAND>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
dmmf Output the DMMF from the loaded data model
dmmf-to-dml Convert the given DMMF JSON file to a data model
execute-request Executes one request and then terminates
get-config Get the configuration from the given data model
help Prints this message or the help of the given subcommand(s)
The prisma version hash is the latest git commit at the time the binary was built.
There are two test suites for the engines: Unit tests ("Cargo tests") and integration tests ("Connector TestKit").
The Unit tests are implemented in the Rust code. They test internal functionality of individual crates and components.
The Connector TestKit is a separate Scala project found at
./query-engine/connector-test-kit
that runs GraphQL queries against isolated
instances of the query engine and asserts that the responses are correct.
Prerequisites:
- Installed Rust toolchain.
- Installed Docker and Docker-Compose.
- Installed Java, Scala, SBT (Scala Build Tool).
- Installed
direnv
, thendirenv allow
on the repository root.- Alternatively: Load the defined environment in
./.envrc
manually in your shell.
- Alternatively: Load the defined environment in
Setup:
There are helper make
commands to set up a test environment for a specific
database connector you want to test. The commands set up a container (if needed)
and write the current_connector
file, which is picked up by the integration
tests:
make dev-mysql
: MySQL 5.7make dev-mysql8
: MySQL 8make dev-postgres
: PostgreSQL 10make dev-sqlite
: SQLite
As an optional but recommended step, you can run the tests by setting up an
IntelliJ project for ./query-engine/connector-test-kit
, which makes test
results much more accessible. You need to install the Scala plugin for Intellij
if you want to do so.
Remember to set IntelliJ to use the version 8 of OpenJDK distribution.
*On windows:
If not using WSL, make
is not available and you should just see what your
command does and do it manually. Basically this means editing the
current_connector
file and starting the needed Docker containers.
To actually get the tests working, read the contents of .envrc
. Then Edit environment variables for your account
from Windows settings, and add at least
the correct values for the following variables:
SERVER ROOT
should point to the root directory ofprisma-engines
project.PRISMA_BINARY_PATH
is usually%SERVER_ROOT%\target\release\query-engine.exe
.MIGRATION_ENGINE_BINARY_PATH
should be%SERVER_ROOT%\target\release\migration-engine.exe
.
Other variables may or may not be useful.
Run:
If you're using Intellij, you can run all tests by right-clicking
src/test/scala
> Run ScalaTests
.
If you want to use the command line, start sbt
in
./query-engine/connector-test-kit
, then execute test
in the sbt shell.
Prerequisites:
- Installed Rust toolchain.
- Installed Docker and Docker-Compose.
- Start all test databases with
make all-dbs
.
Run:
Run cargo test
in the repository root.
- Prevent compiler warnings
- Use Rust formatting (
cargo fmt
)
If you have a security issue to report, please contact us at security@prisma.io