PostGraphile v4 Released

After many months of development, testing and iteration it is my great pleasure to announce that PostGraphile v4 is officially available! Everyone using PostGraphQL v3 should upgrade to PostGraphile at their earliest convenience — if you need help with the migration then pop into our Discord chat.

Despite 80% of the codebase having been replaced with the new Graphile GraphQL Engine, v4 manages to achieve very high compatibility with v3, so most users should find the upgrade fairly painless.

The main focusses of v4 have been performance, customisability and stability.

Performance

PostGraphile performance has been greatly improved thanks to the new Graphile Engine which enables us to compile an entire GraphQL query tree into just one SQL statement. This then passes the task of efficiently executing your query over to the heavily optimised query planner in PostgreSQL, which uses advanced techniques such as relational algebra and genetic algorithms to find the fastest plan quickly. We’ve also performed a large number of optimisations in JavaScript-land, which has lead to code that is more easily optimised by the JIT, and reduced work for the garbage collector — resulting in a 90%+ reduction in peak memory usage. We see typical performance improvements for webpage queries at around 17×, but the more complex the query is, the better PostGraphile v4’s performance — for a 4-level deep query we hit 55× the performance of v3!

Customisability

Reading over the GitHub issues when I became maintainer of the (then) PostGraphQL project over a year ago, I realised that quite a few people desired the ability to customise their GraphQL schema. There were even a small number of people maintaining public forks of PostGraphQL so that they could add that one feature that was important to them; but these forks would quickly become out of date as the effort required to keep them in sync was too great. PostGraphQL also exposed too much by default, making schemas seem huge and unwieldy at times. It was clear to me that PostGraphile needed to solve these issues — doing more for the user out of the box, giving them more control over the generated GraphQL schema, and allowing users to enhance their schemas as they saw fit; so I set out to address these issues in version 4.

Out of the box, PostGraphile now ignores resources that come from PostgreSQL extensions, so you can now use the default public schema in PostgreSQL without your GraphQL being flooded with helper functions from extensions such as citext and pgcrypto(you can opt out of this should you so desire).

Version 4 also introduces the --no-ignore-rbac toggle which inspects the database permissions and omits things that the user has not been granted access to. This means that if you don’t grant SELECT on a table to your PostGraphile role, it will not appear in the generated schema. If you only grant UPDATE on two columns in your table, then only those two columns will be available in the update mutation. We highly recommend that all users enable this flag, it will probably be enabled by default in v5.

Another feature v4 introduces is smart comments. Smart comments enable you to add tags to tables, columns, functions, constraints, etc. so that the system can handle them slightly differently. For example, you can use the @omit all tag to prevent the generation of the allFoos root query field, or the @deprecated tag to mark a field as deprecated. You can use @name and variants to give a different name to a field or type in the generated GraphQL schema. And this functionality is not limited to these specific tags — plugins can also be influenced by smart comments.

And speaking of plugins — v4 introduces a powerful plugin system powered by Graphile Engine. This GraphQL engine was built from the ground up to enable incredible performance and extensibility. And we’re not kidding — in fact the entire schema generation in PostGraphile is powered by over 35 plugins, and you can add, remove or replace plugins to get the schema that you desire without having to maintain a fork of the entire project. A community of plugin builders has formed during the testing period of PostGraphile v4 and has built some really amazing plugins — one to check out in particular is Matt’s connection filter plugin which adds powerful filtering capabilities to PostGraphile connections.

The naming system (“inflector”) in PostGraphile is also pluggable, so if you don’t like how we manipulate the names of your database fields, or if you don’t like our allRows naming, you can change it easily. You can check out my inflector simplifier plugin to see this in action (I definitely recommend using this once you’re familiar with PostGraphile), or make your own with our handy makeAddInflectorsPlugin helper.

Stability

Version 4 fixes a large number of bugs and edge cases that were present in v3. It also focusses on reducing memory usage, helping your servers run faster for longer. One of the reasons for the long development and testing phase has been that we wanted to make sure that v4 was a solid foundation on which to build, ensuring that we do not cause any breaking changes in the future. Thanks largely to the community testing it and filing issues, writing powerful plugins, and pushing the boundaries of the software, I’m very confident in today’s release.

We’ve also made it a lot easier for users to figure out what’s going wrong — the errors that PostGraphile outputs now are no longer cryptic errors as they have been in the alpha and beta periods, but instead helpful errors detailing not only what went wrong, but in many cases hinting at how you might fix it. If you come across any cryptic error messages, please do file an issue so that we can fix it.

Getting Started

We’ve dedicated a lot of time to the PostGraphile documentation, and this will be continually improved over the coming weeks and months. We’ve included a full Version 4 Feature Guide and Version 3 to Version 4 Migration Guide — so do check them out whilst you upgrade.

Getting started with PostGraphile is as easy as giving it your PostgreSQL database connection string, e.g. for a local database called my_db, assuming you already have Node.js 8.6 or higher installed you can use the bundled npx utility and run:

npx postgraphile -c my_db --watch

The watch mode will monitor your PostgreSQL database for changes (added or removed tables, columns, constraints, comments, functions, etc) and automatically update the GraphQL schema. Our built in GraphiQL UI will also automatically update the documentation browser, without losing your state.

Please Support PostGraphile Development

PostGraphile version 4 has been a labour of love, but sadly love doesn’t pay the bills! Sponsorship is now close to funding a day per week dedicated to PostGraphile development, and this support is growing every month which is already leading to more features and faster releases. Please consider if you can support PostGraphile development via Patreon — a regular donation means more time spent on PostGraphile.

Whether you can sponsor PostGraphile or not, there are other ways you can help:

• ⭐ Star the repository on GitHub
• Talk about PostGraphile on social media
• Write blog posts about using PostGraphile
• Demonstrate your projects at local meet ups

And follow our new Twitter account @GraphileHQ for more updates.

The more people that use and support PostGraphile, the faster fixes and features can be added, and everyone benefits!

I want to take this opportunity to say a huge THANK YOU to the community for supporting my work on PostGraphile, without you version 4 would not be nearly as exciting a release!