If you have a security issue to report, please contact us at security@prisma.io with as much details as possible so that it can be handled confidentially.
Prisma has a large and supportive community of enthusiastic application developers. You can join us on Slack and here on GitHub Discussions.
If you have found a bug or have a feature request then please create an issue in this repository (please search first in case a similar issue already exists).
Want to write a test? Please have a look at our TESTING.md.
Prisma consists of a mono-repo for all TypeScript code. To setup and build the packages, follow these steps:
git clone https://github.com/prisma/prisma.git
npm i -g pnpm@6 --unsafe-perm
cd prisma
pnpm i
pnpm run setup
Note for Windows: Use the latest version of Git Bash
- Node.js
>=12.2
minimum, latest LTS is recommended - Install
yarn@1
(for building a "pack" version of the client) - Install
pnpm@6
(for installing npm dependencies) - Install
docker
(for managing test databases) - Install
ts-node
(for running Node scripts written in TypeScript)
-
Use TablePlus for managing sqlite database fixtures.
-
We use the Jest test framework. Its CLI is powerful and removes the need for npm scripts mostly. For most cases this is what you need to know:
yarn jest <fileNamePattern> -t <testNamePattern>
-
Some integration tests in these packages use Jest's
each
feature. If you only want to run a subset of the test cases, simply leverage the-t
flag on the command line (see above point). For example inpackages/cli
here is how you would run Just thefindOne where PK
cases for sqlite integration:yarn jest integrate.sqlite -t 'findOne where PK'
Also you can piggy back flags onto existing npm scripts. For example the above could be rewritten as:
yarn test:sqlite -t 'findOne where PK'
cd packages/client
ts-node fixtures/generate.ts ./fixtures/blog/ --skip-transpile
cd fixtures/blog
export DB_URL=YOUR_DATABASE_URL
For this step you might find our docker-compose setup helpfulnpx prisma db push --skip-generate
ts-node main
What the ... is DMMF? It's the Datamodel Meta Format. It is an AST (abstract syntax tree) of the datamodel in the form of JSON.
The whole Prisma Client is just generated based on the DMMF, which comes from the Rust engines.
Oftentimes, the Rust team did a change in DMMF, which you now need to integrate. How to do that?
The first step is to identify, which new @prisma/engines
version you want to use.
Either have a look in the Versions tab in https://www.npmjs.com/package/@prisma/engines or check out npm info @prisma/engines
in your terminal.
Let's say you determined, that you want to upgrade to 2.20.0-14.f461292a2242db52d9f4c87995f0237aacd300d2
. To upgrade your local workspace, run this command to upgrade both @prisma/engines
and @prisma/engines-version
:
pnpm update -r @prisma/engines@2.20.0-14.f461292a2242db52d9f4c87995f0237aacd300d2 @prisma/engines-version@2.20.0-14.f461292a2242db52d9f4c87995f0237aacd300d2
In the ./packages/client
dir, now open sandbox/dmmf.ts in your VSCode editor.
Either run ndb
in your terminal to debug the file: ndb -r ts-node/register ./sandbox/dmmf.ts
Or
- Open
.vscode/launch.json.default
and save it as.vscode/launch.json
. - Then click on the debug icon in VSCode:
- Then select in the dropdown of possible runner options
Client - Current TS File
- Then just press the green play button
- You should now be able to go through the DMMF and have a look at the json structure
You can always check out the test of our "exhaustive schema", where we test the fully generated client, which depends on the dmmf:
pnpm run test exhaustive
Usually, dmmf changes are also visible in the tests of the sdk:
cd ./packages/sdk
pnpm run test
If there is a change in the snapshots, only accept them if you're 100% certain, that these changes are expected. If not, please always ping the Rust team, if this is an intended change.
We have two kinds of integration tests:
- Testing basic query functionality - located in
src/integration-tests/src/__tests__/integration
- Testing the client in mini projects - located in
src/client/src/__tests__/integration
To run any of these, start the test databases (see readme for various ways to run these)
cd docker
docker-compose up -d
The integration tests consisting of mini project are located in src/integration-tests/src/__tests__/integration
Start the tests
cd packages/integration-tests
pnpm run test
The integration tests consisting of mini project are located in src/client/src/__tests__/integration
Start the tests
cd packages/client
pnpm run test integration
Notes:
- To update the snapshots run script with Yarn and add
-u
flag like this:yarn run test -u
- If on a patch branch then the latest engine binary patch version for that semver-minor series will be used. If not on a patch branch then the current
master
engine binary version will be used. A patch branch is a branch whose name matches semver pattern2.<minor>.x
. The Test suite will log which engine binary is being used at the start of testing.
Prisma Client JS integration tests are located in https://github.com/prisma/prisma/tree/main/packages/client/src/__tests__/integration
If you want to create a new one, we recommend to copy over the minimal test and adjust it to your needs.
It will give you an in-memory Prisma Client instance to use in the test. It utilizes the getTestClient
helper method.
Sometimes you need an actual generated Client, that has been generated to the filesystem. In that case your friend is generatedTestClient
. An example that uses this helper is the blog example
If you want to debug a project that you have on your local dev machine and run it with your local Prisma Client, we have something for you ;) The Prisma Client JS core authors need this all the time to debug projects, especially if databases like Postgres or MySQL are involved.
Click to expand
Let's say your project that uses Prisma Client is located in ~/reproduction/repro1
. We got this fresh reproduction from a support engineer or a Prisma user.
- If you did not already, please go into
./packages/client
in your terminal. - The magic script is located in
fixtures/generate.ts
. It has a couple of different modes in which it can run, depending on your needs.
If you execute ts-node fixtures/generate.ts ~/reproduction/repro1
, a Prisma Client will be generated to ~/reproduction/repro1/node_modules/.prisma/client
and ~/reproduction/repro1/node_modules/@prisma/client
.
It is the nearest it gets to a "production" environment, in which it uses npm pack
of your local client
package. That means if you want to see any change in this approach, you need to run yarn build
every time, before you re-generate the client for your reproduction project.
Although yarn build
is already quite quick, we might even have something faster for you:
In this case, we're not generating the Prisma Client as usual into ./project/node_modules/@prisma/client
but just to ./project/@prisma/client
.
That means in your project you need to change the import. What is the advantage of this approach? You don't need to run yarn build
every time you have a change.
Note however, that this just works with TypeScript, as that client in ./@prisma/client
directly imports the runtime from the ./src/runtime/
dir in your local client code.
You will need to have a tsconfig.json
in that project, with strict mode disabled. You can use the one of the blog fixture project.
Faster iterations (also JS): ts-node fixtures/generate.ts ~/reproduction/repro1 --skip-transpile --built-runtime
There are also cases, in which you still want faster iterations, but have a JavaScript example and don't want to port it to TypeScript.
In this case, you can still do yarn build
, but you don't need to rerun ts-node fixtures/generate.ts ...
all the time.
It will be a client, that again gets generated to ./project/@prisma/client
(note that the node_modules is intentionally missing here) and points to the already built runtime dir in ./runtime
in the client code.
With these 3 options you should be able to tackle any bug in any reproduction you get :)
Note, that sometimes you need to debug bugs in the engine-core
package.
You'll need to build engine-core
with yarn build
if you want that change to end up in the reproduction project.
If you have your local blog fixture running, you can now do changes to TSClient.ts
and re-execute npx ts-node fixtures/generate.ts ./fixtures/blog/
.
When doing changes and working on a fixture use yarn build && rm -rf fixtures/blog/node_modules/ && ts-node fixtures/generate.ts fixtures/blog
If you want to use the local runtime in the blog fixture, run
ts-node fixtures/generate.ts ./fixtures/blog/ --skip-transpile
Changes to query.ts
will then be reflected when running fixtures/blog/main.ts
ENV | Info |
---|---|
FORCE_PANIC_MIGRATION_ENGINE=1 | Forces the Migration Engine to Panic |
FORCE_PANIC_INTROSPECTION_ENGINE=1 | Forces the Introspection Engine to Panic |
cd packages/migrate/fixtures/blog
ts-node ../../src/bin.ts dev
cd packages/introspection
mkdir test && cd test
ts-node ../src/bin.ts
cd packages/cli
mkdir test && cd test
ts-node ../src/bin.ts generate
cd docker
docker-compose up -d
docker-compose logs -f app
We structure our messages like this:
<type>(<package>): <subject>
<BLANK LINE>
<body>
Example
feat(client): new awesome feature
Closes #111
List of types:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing or correcting existing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
List of packages:
- cli
- client
- debug
- engine-core
- generator-helper
- migrate
- react-prisma
- sdk
- tests
To Generate/Update install GraphViz
ts-node scripts/graph-dependencies.ts
Pull Request authors must sign the Prisma CLA, it will show up in an automated comment after you create a PR.
If you cannot or do not want to sign this CLA (e.g. your employment contract for your employer may not allow this), you should not submit a PR. Open an issue and someone else can do the work.