Skip to content
Execute one command (or mount one Node.js middleware) and get an instant high-performance GraphQL API for your PostgreSQL database!
JavaScript TypeScript Shell Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github sponsorship: add FUNDING.yml file Jul 20, 2019
assets feat(favicon): use PostGraphile favicon (#889) Oct 30, 2018
docker feat(docker): update Dockerfile to build fresh rather than install fr… May 17, 2019
examples docs(example): replace deprecated cli options (#1196) Nov 22, 2019
postgraphiql fix(graphiql): fix operation detection on multi-op documents (#1191) Nov 20, 2019
resources chore: move from TSLint to ESLint (#1157) Sep 24, 2019
scripts chore(deps): upgrade graphile-utils (#1192) Nov 20, 2019
src feat(tags): file watching plugin for library users (#1190) Nov 20, 2019
typings chore: move from TSLint to ESLint (#1157) Sep 24, 2019
.dockerignore feat(docker): update Dockerfile to build fresh rather than install fr… May 17, 2019
.editorconfig 🌅 Oct 9, 2016
.eslintignore chore: move from TSLint to ESLint (#1157) Sep 24, 2019
.eslintrc.js chore: move from TSLint to ESLint (#1157) Sep 24, 2019
.gitignore feat(perf): performance enhancements (#1077) May 17, 2019
.npmignore chore: move from TSLint to ESLint (#1157) Sep 24, 2019
.prettierignore feat(graphql): subscriptions and live queries enhancements (#998) Feb 21, 2019
.travis.yml chore(ci): use yarn cache Apr 18, 2019
CHANGELOG.md 4.5.0 Nov 22, 2019
CONTRIBUTING.md doc(CONTRIBUTING): link to docker instructions in wiki (#1185) Nov 18, 2019
Dockerfile fix(docker): add missing files to Dockerfile Nov 24, 2019
ISSUE_TEMPLATE.md Redirect chat to discord Oct 11, 2018
LICENSE.md docs: update README (#861) Sep 22, 2018
README.md sponsorship: update README.md (#1176) Nov 7, 2019
SPONSORS.md sponsorship: Update for October & November, thank you 🙏 (#1175) Nov 7, 2019
TROUBLESHOOTING.md docs(TROUBLESHOOTING): add instructions to file (#833) Aug 15, 2018
cli.js feat(tags): file watching plugin for library users (#1190) Nov 20, 2019
index.js feat(tags): file watching plugin for library users (#1190) Nov 20, 2019
isTurbo.js feat(tags): file watching plugin for library users (#1190) Nov 20, 2019
package.json 4.5.0 Nov 22, 2019
plugins.d.ts feat(tags): file watching plugin for library users (#1190) Nov 20, 2019
plugins.js feat(tags): file watching plugin for library users (#1190) Nov 20, 2019
postgraphile chore(deps): upgrade graphiql dependencies (#1055) Apr 18, 2019
prettier.config.js feat(jwt): add support for buffer as JWT secret (#1015) Mar 7, 2019
rmlocal.sh chore(types): remove @types/graphql (#1152) Sep 3, 2019
run-pg fix(dev): change shebang from /bin/bash to /usr/bin/env bash (#983) Jan 31, 2019
sponsors.json sponsorship: update sponsors.json Nov 12, 2019
tsconfig.json feat(tags): file watching plugin for library users (#1190) Nov 20, 2019
yarn.lock chore(deps): upgrade graphile-utils Nov 22, 2019

README.md

PostGraphile

Patreon sponsor button Discord chat room Package on npm MIT license Follow

Instant lightning-fast GraphQL API backed primarily by your PostgreSQL database. Highly customisable and extensible thanks to incredibly powerful plugin system. Formerly "PostGraphQL".

Documentation: graphile.org/postgraphile

Crowd-funded open-source software

To help us develop this software sustainably under the MIT license, we ask all individuals and businesses that use it to help support its ongoing maintenance and development via sponsorship.

Click here to find out more about sponsors and sponsorship.

And please give some love to our featured sponsors 🤩:

Chad Furman
Chad Furman
Storyscript
Storyscript
Point72 Ventures
Point72 Ventures

About

GraphQL is a new way of communicating with your server. It eliminates the problems of over- and under-fetching, incorporates strong data types, has built-in introspection, documentation and deprecation capabilities, and is implemented in many programming languages. This all leads to gloriously low-latency user experiences, better developer experiences, and much increased productivity. Because of all this, GraphQL is typically used as a replacement for (or companion to) RESTful API services.

PostgreSQL is the self-proclaimed “world’s most advanced open source database,” with each new release bring more amazing features and performance gains. Thinking of your database as a plain CRUD store is now an archaic viewpoint as modern PostgreSQL can do so much for you — from authorization with Row-Level Security (RLS, introduced in PG9.5), through Foreign Data Wrappers (FDW), to real time notifications with LISTEN/NOTIFY.

PostGraphile pairs these two incredible technologies together, helping you not only build applications more rapidly, but to build lightning-fast applications. PostGraphile allows you to access the power of PostgreSQL through a well designed, extensible, customisable and incredibly performant GraphQL server. It automatically detects tables, columns, indexes, relationships, views, types, functions, comments, and more - providing a GraphQL server that is highly intelligent about your data, and that automatically updates itself without restarting when you change your database schema.

With PostGraphile, a well designed database schema should serve the basis for a well thought out API. 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 than 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. Once you need to expand beyond this, we have a powerful plugin system including many community contributed plugins. 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!

PostGraphile at GraphQL Summit

Hear from the current maintainer Benjie at GraphQL Finland about the benefits of Database-Driven GraphQL Development:

Database Driven GraphQL Development at GraphQL Finland

Usage

Documentation: graphile.org/postgraphile

You can use PostGraphile via the CLI, as a Node.js middleware, or use the GraphQL schema directly. Make sure to check out the full usage instructions on the documentation website. We also have a PostgreSQL schema design guide you can follow to build a fully functional PostGraphile API.

CLI

To get started you can install PostGraphile globally:

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

When you're ready to use PostGraphile for your own project, you're advised to install it locally with yarn, and run it with npx:

yarn add postgraphile
npx postgraphile --help

Middleware

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

yarn add postgraphile
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 --init graphile/postgraphile --help

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

docker run --init -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:

Requirements

Full requirements are on the website, but a basic summary is:

  • Node v8.6+
  • PostgreSQL 9.6+ (officially; but 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 👍

You can’t perform that action at this time.