gridl/postgraphile

Execute one command (or mount one Node.js middleware) and get an instant high-performance GraphQL API for your PostgreSQL database!

PostGraphile

An instant, highly-performant GraphQL API for your PostgreSQL database, extensible via a powerful plugin system.

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.

---

GraphQL is a powerful new way to query your servers - it's typically used as a replacement for, or companion to, RESTful API services. Introduced by Facebook in 2015, it features strong data typing, built in introspection and documentation capabilities, and solves among many other things the problems of over- and under-fetching data. It's particularly great for mobile clients where minimizing number of requests, latency, and payload size are all critically important tasks - but this awesome mobile experience makes regular webpages much smoother too.

PostgreSQL is the self-proclaimed “world’s most advanced open source database,” and despite its over 20 year maturity this still rings true. New versions of PostgreSQL are released regularly, and each new major version brings incredible new features, not to mention massive performance gains. Seeing your database as just a plain CRUD store is now an archaic viewpoint, modern PostgreSQL can do so much for you: from enforcing business logic with Role-Based Access Control (RBAC) and Row-Level Security (RLS), through communicating with other systems via Foreign Data Wrappers, to real time notifications with LISTEN/NOTIFY, PostgreSQL can handle it all with ease.

PostGraphile pairs these two incredible technologies together to help you not only build applications more rapidly, but to build faster applications! Access the power of PostgreSQL through a well designed, extensible, customisable and incredibly performant GraphQL server. PostGraphile uses PostgreSQL reflection APIs to automatically detect tables, columns, indexes, relationships, views, types, functions, comments, and more - providing a GraphQL server that is highly intelligent about your data. PostGraphile can automatically detect changes to your database (e.g. new columns or tables) and instantly rebuild and serve the updated GraphQL API - even updating GraphiQL automatically! This leads to incredible productivity gains, and helps developers multiply their impact.

With PostGraphile, a well designed database schema should be all you need to serve a well thought out API; and if it isn't - well, we have a powerful plugin system including many community contributed plugins! 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 walk-through of building an application with PostGraphile in under 7 minutes. This was using v2 (then called PostGraphQL); 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

Read More

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:
  • Custom queries
  • Custom mutations
  • Computed columns
• 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

Requirements

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

Caveats:

• PostGraphile does not have automated tests on Windows, if you notice any issues please file them (or send a PR!)

Supporting PostGraphile

The fastest and easiest way you can help PostGraphile thrive is by sponsoring ongoing development and maintenance.

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

Commercial support, consultancy and development services are available direct from the maintainer; see Professional Services for more information, or get in touch!

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

Thanks

Huge thanks to the individuals and companies who sponsor PostGraphile's development - their financial contributions enable more time to be spent on the project: from bug fixes, to code review, to new features! If you want to help the project 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 👍