JavaScript TypeScript Shell Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.vscode fix space-before-function-paren Feb 19, 2018
examples docs(TUTORIAL): use missing_ok parameter (#835) Aug 16, 2018
resources chore(sql): remove unused resources (see graphile-build-pg instead) Mar 10, 2018
scripts fix(dev): remove '--ignore' flag from ts-node Aug 16, 2018
src fix(cors): fix allowed methods header, allow X-Apollo-Tracing (#838) Aug 17, 2018
typings feat(hooks): enable enhancing PostGraphile middleware via hook (#814) Jul 25, 2018
.dockerignore feat(docker): Docker Image (#496) Jul 9, 2017
.editorconfig 🌅 Oct 9, 2016
.gitignore feat(types): ship automatic TypeScript typings (#794) Jul 21, 2018
.npmignore Even smaller bundle Jul 15, 2017
.travis.yml chore: update requirements Feb 23, 2018
CONTRIBUTING.md feat(types): ship automatic TypeScript typings (#794) Jul 21, 2018
Dockerfile chore(Dockerfile): update Dockerfile to install from npm Jun 8, 2018
ISSUE_TEMPLATE.md PostGraphQL -> PostGraphile Feb 23, 2018
LICENSE chore(*): add license Oct 9, 2016
README.md docs(README): update README Jun 8, 2018
SPONSORS.md sponsorship: update sponsors for August 🙏 (#823) Aug 13, 2018
TROUBLESHOOTING.md docs(TROUBLESHOOTING): add instructions to file (#833) Aug 15, 2018
package.json 4.0.0-rc.3 Jul 25, 2018
prettier.config.js chore(lint): add semicolons (via `prettier`) (#807) Jul 21, 2018
tsconfig.json feat(types): ship automatic TypeScript typings (#794) Jul 21, 2018
tslint.json chore(lint): use more standard TSLint config (#810) Jul 23, 2018
yarn.lock chore(deps): upgrade postgraphile-core (#817) Jul 25, 2018

README.md

PostGraphile

Package on npm MIT license Gitter chat room Patreon donate button Donate Follow

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!

PostGraphile at GraphQL Summit

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:

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 👍