Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
326 lines (241 sloc) 9.91 KB


The PostGraphile project welcomes all contributors, we want to invest in you so you can invest back into PostGraphile. Together we can make great software that enables developers to build powerful applications in much less time then would previously have been taken. This document aims to help you get started contributing to the project.

Development environment

First of all, our development environment is focussed around Unix tools. If you are on Windows, you may need to use something like Docker or a VM to help you develop.

Since PostGraphile is mostly powered by Graphile Engine the best way to develop it is to do it in the context of a Graphile Engine build so that you may dig into the depths if you need to.

We use yarn workspaces, so it's very important that you use the yarn package manager rather an npm whilst developing PostGraphile.

npm install -g yarn

Before we start, check that you're running up to date versions of the relevant tools, you should be running at least:

$ node --version
$ yarn --version
$ git --version
git version 2.18.0
$ watchman --version # optional

(If you don't have watchman that's fine, but it helps when watching large numbers of files. On Mac you can install it using homebrew: brew install watchman)

To get started, we're going to check out graphile-engine, and then we're going to check out postgraphile inside of graphile-engine. With a few tweaks this will enable postgraphile to use the development version of the modules in graphile-engine without needing to perform yarn link etc.

It should be safe to copy and paste these commands into your terminal (one at a time), but if you're using zsh you may want to run this first so that comments are ignored:

set -k

Okay, here's the setup:

# Clone graphile-engine:
git clone graphile-engine

# Clone postgraphile _inside of_ graphile-engine:
git clone graphile-engine/postgraphile


# Initial setup for graphile-engine
cd graphile-engine

# Install deps:
# Monorepo stuff:
yarn lerna bootstrap
# Run initial build:
yarn prepack:all


# Initial setup for postgraphile
cd postgraphile

# Install deps:
# Remove deps that should be served by the parent graphile-engine:
# Builds GraphiQL, images, etc so they can be require()d:
yarn make-assets


Graphile Engine

Graphile Engine is built in a mixture of TypeScript and Flow (we're slowly migrating to TypeScript); which means it has a compile step. For developer productivity we don't incur this compilation cost every time we run the development version of PostGraphile, instead we require the compiled code in most places. This means that we must watch the source code for changes so that when we run the compiled code it's not out of date. To do this, in the root of graphile-engine, run yarn watch:

yarn watch

This will compile everything, and then monitor for changes and compile just the changed files. Every time a file is compiled it will be listed in the output - be careful to check for errors!

You should leave this watch process running, so open another terminal to do further work.


First, change into the postgraphile directory (graphile-engine/postgraphile/).

To run PostGraphile in development, you can use the scripts/dev command. This command emulates the postgraphile command, and it has two modes. If you want the scripts/dev command to exit when postgraphile would, add two hyphens, e.g.

# Will run once and exit on error or `-X` option
scripts/dev -- -c postgres://localhost/my_db -s my_schema --watch --enhance-graphiql

The -- makes scripts/dev act more like a regular build - i.e. exiting on the -X commands or when an error occurs.

If, however, you want scripts/dev to automatically restart whenever you change the PostGraphile or Graphile Engine source code, run it without the --. To manually restart the server type in rs and hit enter while scripts/dev is running.

# Will monitor the source for changes and restart automatically
scripts/dev -c postgres://localhost/my_db -s my_schema --watch --enhance-graphiql

Updating or changing branches

Due to this peculiar setup, when you want to update or switch branches, you have to do an extra couple steps than you might expect.

Graphile Engine

(In the graphile-engine folder.)

Thanks to yarn workspaces, updating the graphile-engine folder is straightforward:

git pull --rebase # or checkout a branch, or whatever
yarn # update deps

If you're running yarn watch in the graphile-engine folder then it's probably a good idea to restart it incase any of the dependencies have changed.


(In the graphile-engine/postgraphile folder.)

git pull --rebase # or checkout a branch, or whatever
yarn # update deps
./ # Remove deps that should be served by the parent graphile-engine

The ./ script is the one you must remember to run again - otherwise yarn will restore the release versions of postgraphile-core, graphile-build-pg and graphile-build, thus your local changes won't be represented.


PostGraphile uses Jest for testing to take advantage of Jest’s snapshot feature. We test against a local database, so make sure PostgreSQL is running on localhost:5432.

Graphile Engine

Graphile Engine uses a user-configurable test database. For historic reasons, Benjie calls it pggql_test (this is from before Graphile Engine had a name!), so we'll use that name here:

createdb pggql_test

We must then export a TEST_DATABASE_URL environment variable so the tests know where to install. WARNING: this database will be overwritten!

export TEST_DATABASE_URL="postgres://localhost/pggql_test"

Then you can run the tests with

yarn test

This takes a while; I'd advise that you focus on the integration tests in postgraphile-core in most cases; and since we're using jest you can pass a filter such as queries to only run tests with a file name that contains the word queries:

cd packages/postgraphile-core
yarn test queries


To run PostGraphile tests you will need to first create the postgraphile_test database:

createdb postgraphile_test

Then run the test suite with:

yarn test

When developing PostGraphile, we recommend using the Jest watch mode feature. So instead you would run tests like so:

yarn test --watch

(If you get an error about too many open files, consider installing watchman as mentioned above.)

Now, only the tests in the files you have changed will be run. There are some slow tests in the PostGraphile suite so hopefully this should make your development time faster. Once you are in watch mode, Jest will present you with some options you can use to better configure your testing experience.


We make use of the Jest snapshot feature. Even when you change small things the snapshot tests are likely to fail, this is expected. To update the snapshots so that the tests pass again, you can press u if you're running in watch mode, or you can run yarn test -u. You should carefully review the changes to the snapshots to ensure they're what you intended. Commit the changes to the snapshots and the changed snapshots will be reviewed along with the rest of your changes in the PR review process.


PostGraphile uses TSLint and Travis CI to test builds and enforce lint rules:


The instance of GraphiQL used by PostGraphile is a create-react-app located in postgraphiql. When developing PostGraphile (running scripts/dev only), GraphiQL will run on a different port to take advantage of the create-react-app developer experience.

Note that postgraphiql has it's own package.json and yarn.lock because it depends on a specific version of GraphQL which is different from the wide range supported by PostGraphile/Graphile Engine. When we build PostGraphile before publishing (with scripts/build), GraphiQL is built into a resources served by the PostGraphile middleware people import into their projects.

Commit messages

PostGraphile team use karma-style commit messages: a type (feat/fix/chore/docs/etc.), a scope (graphql/postgraphile/examples/tests) and then the commit message. Commit messages are written in the imperative tense.

Here’s a few examples:

feat(ci): run against multiple postgres versions
fix(postgraphile): fix opaque error messages
chore(docs): rename anonymous role to default role

When committing to a branch or a PR you do not need to adhere to this format. However, all commits to the master branch must be in this format. Often all of the commits in a PR will be squashed and a commit message of this format will be written to summarize the changes.

You must use one of the following types:

  • chore
  • docs
  • feat
  • fix
  • refactor
  • style
  • test

Common scopes are as follows. You are not required to use any of the following scopes and may instead invent your own. These are just a few that get commonly used.

  • *
  • postgraphile
  • graphql
  • interface
  • postgres
  • package
  • scripts
  • examples
  • ci


Here are some resources that will help you learn more about Postgres and GraphQL so that you may understand more of what is going on inside PostGraphile.

You can’t perform that action at this time.