Skip to main content

PostGraphile Introduction

Migration Guide: V4 to V5

Coming from PostGraphile Version 4? Check out the migration guide!

If you already use PostgreSQL then you understand the value that a strongly typed and well defined schema can bring to application development; GraphQL is the perfect match for this technology when it comes to making your data layer accessible to your frontend application developers (or even API clients).

PostGraphile uses automation and intelligent defaults to eradicate the time consuming and repetitive parts of building a best practices GraphQL API, whilst giving you the tools you need to customize and extend your schema to be exactly what you need. And because it’s powered by Grafast it’s extremely unlikely that you’d be able to build a GraphQL API using traditional GraphQL/DataLoader patterns that’s anywhere near as fast as a PostGraphile API — it truly runs rings around traditional API development practices.

Built on a plugin system, you can easily pick and choose the features that you want in your API (and even develop your own or mix in features from the community). Using the smart tags system you can easily tweak which entities appear, and how they’re exposed. If you ultimately decide an auto-generated GraphQL API may not be for you, PostGraphile has an ‘export’ feature so your generated API can be exported as executable JavaScript code which you can then maintain yourself ─ there's no lock-in.

Your schema should reflect client needs, not just database tables

PostGraphile doesn't have to be (and generally should not be) a “1-to-1 map” of your database.

Whilst its common for a significant portion of your data model to remain broadly aligned from database through to frontend, that's not true of every resource. Thus, PostGraphile gives you a wide array of tools and techniques to sculpt your schema to fit frontend needs, whilst still eliminating unnecessary work for the parts of your data model that are standard and consistent throughout the stack.

PostGraphile automatically reflects the permissions in your database and only exposes the tables, columns, functions and mutations that are granted to it.

Smart tags and similar techniques allow you to hone the GraphQL schema to your needs: hide or exposing tables/columns/functions, change their naming or presentation, indicate abstract types/polymorphism, or otherwise manipulate the generated schema with simple tagging.

With schema extensions, you can add any types/fields/args that you need to, which can communicate with any data source that Node itself can communicate with. You can also use the plugin interface to wrap plan resolvers with your own logic, which gives huge control over authorization, presentation, filtering, and various other topics.

By exporting the executable schema, you can see the plan resolvers/types/fields that PostGraphile has generated for you and, should you choose to, you can take this code and make it your own — either for the entire schema, or for specific portions of it. This can be used to enable you to evolve your database tables without breaking your GraphQL schema.

We strongly advise that you start with as small a GraphQL API as you can, and then add features to it as you need them, rather than going for a “kitchen sink” approach!

If your company needs a GraphQL API and the data the API serves comes mostly (but not exclusively!) from PostgreSQL databases then PostGraphile can help you craft your perfect GraphQL API in a matter of days, if not hours; saving you weeks if not months of development time.

For databases that already use row-level security you might be able to build a secure, performant and extensible GraphQL API in mere minutes. We still recommend that you take some time to hone your API though!

If you are new to GraphQL we recommend you read through the official introduction to GraphQL here before continuing through the PostGraphile documentation.

Some of the features we offer:

  • Incredible performance - even for your custom logic!
  • Full GraphQL feature-set, including advanced topics such as:
  • Excellent Relay support via our postgraphile/presets/relay preset:
    • Global object identification
    • Cursor pagination
    • Mutation input objects and payloads
  • Massively reduced load on your database without the complexity of caching/cache invalidation
  • Integrates with any authentication middleware available in Node
  • Easily add fields and mutations via JS/TS plugins or database functions
  • Written in pure TypeScript - no binary modules!
  • Export your schema as executable JavaScript code
  • Very fast startup in serverless
  • Bring your own PostgreSQL driver/adaptor (integrate with almost any Postgres client library)
  • Run as a CLI, as a Node.js middleware, or a standalone GraphQL schema
  • Easy customization via smart tags
  • Explain your operations via Ruru (our Grafast-enhanced GraphiQL IDE)
  • Auto-discovered relations
  • Automatic CRUD mutations e.g. updatePost
  • Almost all features are optional, and most can be customized on a per-table, per-column or per-constraint basis (as appropriate)
  • Incredible versatility via a wide array of plugins:
    • Aggregates
    • Powerful filtering
    • Soft deletion
    • Upsert
    • Many-to-many navigation
    • Ordering by related tables
    • Multi-tenancy
    • PostGIS (not yet ported to V5)
    • And many many more...

The easiest way to get started is with the CLI interface; if you have npx installed you can try it out with:

npx pgl -P pgl/amber -e -c 'postgres:///mydb'

(Replace the connection string with a PostgreSQL connection string to your database. If your data is not located in the public schema of your database you can specify a comma-separated list of database schemas with -s a,b,c.)