PostGraphile

Instant GraphQL API for PostgreSQL database


Try it now!

The fastest way to get a full client-facing GraphQL API up and running from a PostgreSQL database schema.

npx postgraphile -c postgres://user:[email protected]/dbname \
  --schema schema_name

See the Quick Start Guide to get PostGraphile up and running.

Note: Run with latest Node LTS v8+. No installation required (npx comes with node performs a temporary install). Connection string is of the format: `postgres://pguser:pg[email protected]host:pgport/pgdb`

Client-facing GraphQL server

PostGraphile is designed to serve GraphQL queries directly from clients such as webpages or mobile apps, leveraging the security features built in to PostgreSQL. Used this way, backend developers can focus solely on specifying the data schema, business logic and permissions using trusted and familiar PostgreSQL - PostGraphile handles making that available as a GraphQL API.

Simple infrastructure

A typical PostGraphile server architecture consists of your PostgreSQL database server and a single Node.js process. There's no containers or other complex setup required in the default stack.

When it comes time to scale, it's easy to scale horizontally using additional servers - PostGraphile is stateless by default.

Solves N+1 queries issues

Using graphile-build's look-ahead features a single root level GraphQL query, no matter how nested, can become just one SQL query - leading to fewer database round-trips and thus blazingly fast performance - typically much greater than that you'd get using DataLoader.

Read more about PostGraphile's stunning performance

Customisable with SQL

PostGraphile has first-class support for your SQL functions, automatically exporting them as custom queries, custom mutations and computed columns as appropriate.

You can further customise the generated schema with our smart comments feature (which allows renaming and removing columns, tables, relations and functions with a straight-forward syntax using PostgreSQL's built in COMMENT facility).

Customisable with JS plugins

The GraphQL schema PostGraphile uses is entirely built from Graphile Build plugins, you can disable any of the built in plugins to restrict the functionality or add additional plugins to extended or enhanced your generated schema.

This allows you to add (or remove) fields, create new types, add functionality, replace functionality or or even tweak existing functionality (e.g. wrapping an existing resolver with your own higher-order function) to gain powerful control over your API.

Build your schema with plugins
buildSchema(plugins);
type Person {
  # @deprecated Use 'name' instead
  # The person's first name
  firstName: String

  #...
Transform your schema with ease
buildSchema([...plugins, DeprecateFromCommentPlugin]);
type Person {
  # The person's first name
  firstName: String @deprecated(
    reason: "Use 'name' instead")

  #...

Fully GraphQL compatible

PostGraphile and Graphile-Build use the reference GraphQL implementation under the hood, so you know they're spec compliant.

PostGraphile supports GraphQL best practices, including: cursor-based connection pagination, global object identification, and the Relay Input Object Mutations Specification.

PostgreSQL schema watching

PostGraphile has an excellent developer experience (DX) when you use the --watch CLI flag - it will automatically re-generate the GraphQL schema when your database changes. What's more, it will automatically reload GraphiQL's documentation too, so you can see your new schema features right away! No need to restart the server!

GraphiQL with auto-generated documentation

PostGraphile comes with GraphiQL built in, set to automatically update the documentation when your database schema changes.

Secure

Using PostgreSQL's Role-Based Access Control (RBAC) and Row-Level Security policies (RLS), PostGraphile leverages the tried-and-tested authentication baked right in to the worlds most advanced open source database - no more reinventing the wheel! Thanks to RLS's granularity it's possible to express complex authorisation logic in simple policies; and because the authentication is in your database you can ensure nothing (not even companion microservices) can bypass it.

PostGraphile uses industry standard JWT authentication, allowing for stateless authentication which also works great with CORS. When used as a middleware it can use any HTTP authentication method that Node.js supports, via the pgSettings function. (A favourite is to use Passport.js for social login.)

Flexible

If you prefer, PostGraphile can be used as a lightning-fast back-end to an alternative client-facing GraphQL schema that might be built using techniques such as "GraphQL schema stitching" or "GraphQL bindings".

If you don't need the GraphQL schema served over HTTP you can simply use the schema directly.

Quick to start

npm install -g postgraphile
postgraphile -c postgres://user:[email protected]/dbname \
  --schema schema_name

Questions, comments or feedback?
Email [email protected]

Keep up to date on Graphile and PostGraphile features/changes. Subscribe to our occasional announcements newsletter: