PostGraphile

An instant, highly-performant GraphQL API for your PostgreSQL database.

Documentation: graphile.org/postgraphile

Note: v1-v3 of this project were named PostGraphQL. A v3-v4 migration guide is available here and you can check out some of the new features here. No more development is taking place on v3, but you can still access its branch here.

The strongly typed GraphQL data querying language is a revolutionary new way to interact with your server. Similar to how JSON very quickly overtook XML, GraphQL will likely overtake REST. Why? Because GraphQL allows us to express our data in the exact same way we think about it.

The PostgreSQL database is the self acclaimed “world’s most advanced open source database” and even after 20 years that still rings true. PostgreSQL is the most feature rich SQL database available and provides an excellent public reflection API giving its users a lot of power over their data. And despite being over 20 years old, the database still has frequent releases.

With PostGraphile, you can access the power of PostgreSQL through a well designed and highly performant GraphQL server. PostGraphile uses PostgreSQL reflection APIs to automatically detect primary keys, relationships, types, comments, and more providing a GraphQL server that is highly intelligent about your data.

PostGraphile believes that a well designed database schema should be all you need to serve well thought out APIs. PostgreSQL already has amazing authorization and relationship infrastructure, why duplicate that logic in a custom API? A PostGraphile API is likely to provide a more performant and standards compliant GraphQL API then any created in house, and can be built in a fraction of the time. Focus on your product and let PostGraphile worry about the API layer.

For a critical evaluation of PostGraphile to determine if it fits in your tech stack, read evaluating PostGraphile for your project.

Introduction

Watch a talk by the original author Caleb at GraphQL Summit for a fast 7 minute introduction to using the PostGraphile project. This was using v2; we're now up to v4 which has many more bells and whistles!

Usage

Documentation: graphile.org/postgraphile

You can use PostGraphile via the CLI, as a middleware, or just use the GraphQL schema directly. Make sure to check out the forum example and especially step by step tutorial for a demo of a PostGraphile compliant schema and authentication.

CLI

Install using npm:

npm install -g postgraphile

…and then just run it! By default, PostGraphile will connect to your local database at postgres://localhost:5432 and introspect the public schema. See the available CLI flags with:

postgraphile --help

Middleware

You can also use PostGraphile as native HTTP, Connect, Express, or Koa (experimental) middleware, e.g.:

import { createServer } from "http";
import postgraphile from "postgraphile";

createServer(postgraphile());

Check out hapi-postgraphile if you're interested in using PostGraphile as a hapi server plugin.

Docker

To run via Docker, simply pass the CLI options to the Docker container:

docker pull graphile/postgraphile
docker run graphile/postgraphile --help

E.g. you might run this command (substituting the relevant variables):

docker run -p 5000:5000 graphile/postgraphile --connection postgres://POSTGRES_USER:POSTGRES_PASSWORD@POSTGRES_HOST:POSTGRES_PORT/POSTGRES_DATABASE --schema app_public --watch

Full documentation for PostGraphile is located at graphile.org/postgraphile.

PostGraphile features include:

Authorization (security) provided by PostgreSQL:
- role-based access control (RBAC)
- row-level security (RLS)
Automatic GraphQL relations from SQL relations
PostgreSQL procedure support:
Development UI (GraphiQL) built in
--watch mode, auto-detects changes in SQL schema, hot-reloads changes into GraphiQL
Automatic documentation, enhanced by PostgreSQL COMMENTs
Schema customisation through smart comments
Simple JWT authentication straight from the database
Cursor-based pagination, Relay (classic & modern) compatible
Global object identifiers (nodeId by default, but Relay-favoured id with --classic-ids)
Relay-compatible mutations
Use direct from the CLI
Use as Express, Connect, or Koa middleware
Just use the generated GraphQL schema

Commercial Support and Consultancy Services

Commercial support, consultancy and development services are available direct from the maintainer; see Professional Services for more information.

Requirements

Node v8.6+
PostgreSQL 9.6+ (currently works with 9.4+)
Linux, macOS or Windows

Caveats:

Support for PG10-specific features is not fully implemented yet
PostGraphile is not tested on Windows, if you notice any issues please file them (or send a PR!)

Contributing and Maintenance

Want to help testing and developing PostGraphile? Check out the contributing document to get started quickly!

The maintainer of this project is @Benjie - follow him on Twitter!

Thanks

Huge thanks to the individuals who sponsor PostGraphile's development - their support helps me spend more time working on the project! If you want the project to advance more rapidly, please join them in supporting this project 🙏

A humongous, heart-felt, thank you to the original author of PostGraphile - Caleb Meredith - for everything he put into PostGraphile! He's now graduated from the project and we all wish him the best for his future ventures!

Thanks also to the people working on PostgREST which was a huge inspiration for this project!

Thanks and enjoy 👍

charlescrain/postgraphile