Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
PostGraphQL V4 - announcing graphile-build #506
In spirit, this is a follow on to Caleb's "My vision for the future of PostGraphQL" #87, to learn about our history I suggest you read that.
Hello everyone, I'm @benjie - the new primary maintainer of PostGraphQL!
I've been a PostGraphQL user for almost a year and have used it on various projects; and I really love how easy it makes starting a new project - all I have to do is build my data schema in my favourite database (PostgreSQL), making sure that the schema itself is secure (using such features as Row Level Security), run
One of the issues that pops up time and again on the GitHub issues is extensibility - you can't add your own types/resolvers to the schema - everything has to be done in PostgreSQL. There's some work in #448 to partially resolve this, but I think I've found a better way...
Another issue has been the performance of the system - it's an excellent reference implementation in terms of accuracy and returning what you'd expect, but under the covers it sometimes generates and runs a very large number of SQL queries and over-fetches data. I attempted to solve this in #342, but since then I think I've found a better way...
Starting with GraphQL as a foundation I tried to imagine a system that could replicate PostGraphQL's benefits whilst remaining customisable, extensible and performant. I imagined PostGraphQL implemented as a number of plugins into a GraphQL schema builder - if you don't want certain functionality, simply don't use that plugin; if you want to add a bit of custom code, write a plugin; if you want to wrap one of PostGraphQL's resolvers with your own, write a plugin; if you... well: you get the point!
To enable this goal, over the past few weeks I've been busy building the following packages in a new monorepo at https://github.com/graphile/graphile-build
I believe this plugin interface can really enable PostGraphQL to grow and flourish. Changes can be implemented as replacements for existing plugins which can be tested outside of core until stable, at which point they can be merged. New functionality can be added in a similar way (subscriptions anyone?) without requiring to fork core. Experiments can be ran; not to mention that individual users can fix their issues with the system without having to have long running forked branches running!
But, alas, it's not quite ready to go just yet. So far I've managed to get the core working sufficiently that I can run my existing projects against it, but there's more to be done before it's release ready. If you're interested in contributing (code, testing, or other support) please get in touch!
Thanks for reading this far, to quote Blaise Pascal: "I would have written a shorter letter, but I did not have the time."
Features required before release:
Features that would be nice to have, but can be implemented after release:
Breaking changes (should be a drop-in replacement for v3 for most people)
Breaking changes I'm aware of (that aren't listed in the checkboxes to be solved above):
Despite the long list, PostGraphQL v4 should be a drop-in replacement for most people - if you see any major issues please let me know.
Have a look at
Really exciting to hear that there is a full time maintainer (and that it's you
I must admit it was disappointing to see it's no longer in TypeScript — I had a quick look and code new code and found it really challenging to make sense of it without having all the type information to tie everything together. If you could share some background or rationale for that I'm sure there'd be an audience for that.
UPDATE: this comment is mostly out of date now - we have Flow, linting, CI and a fairly decent amount of documentation on graphile.org
@bradleyayers Sadly I'm not full time; my work on PostGraphQL is completely unpaid; which also explains the lack of TypeScript: I was working to get a new system up and running as a proof of concept ASAP without knowing exactly what form it would ultimately take - strong typing would have slowed me down considerably at the rate I was iterating. I decided it would be fun to write the code in native JS because that way I wouldn't need transpilers, source maps, or any of that other mess that comes along with compile-to-JS languages - and the debugging tools for Node.js now built into Chrome are outstanding!
Now that the shape of the system is better known I'll probably start typing the system a little at a time with Flow which is pretty useful out of the box and doesn't require as much markup as TypeScript. I also find it to be more flexible and with clearer errors but that may be a familiarity thing.
My hope is that taking the monorepo approach will mean the various parts of the system can be kept fairly separate with clear boundaries and APIs; I've started documenting some of these but haven't got very far yet. I've not even enabled strong linting yet, or CI - all things on my todo list! At the moment the plugins are not as loosly coupled as I'd ultimately like, but I think that's something that will improve over time. My next task is to get schema watching working - once that's up and running I think the interfaces will be fairly stable. Though I should probably think about a "requires/optional/provides" specification for the plugins.
For documentation, we have two main sources currently: https://github.com/postgraphql/postgraphql/tree/master/docs
We can have a "tutorial" page that uses docco to generate a nice UI from comments in a file, then walk the user through it that way.
The docs section consists of two parts, currently mixed together:
I can get a PR together for the existing content in a format that will work on https://github.com/postgraphql/postgraphql.github.io
What else will we need in the v4 docs?
@chadfurman Thanks for pitching in!
We've also got a tiny amount on the wiki and absolutely loads spread throughout the GitHub issues. Would be good to centralise this (and remove the current places so that they don't get built up/added to again!)
Yes - basically usage instructions (PostGraphQL) and advice/best practices (PostgreSQL)
That would be excellent.
The various sub-components of
The v4 usage instructions should be basically the same as V3 (even the library instructions), we may tweak the
We're so close to v4 beta now I can taste it! There's just one more breaking change I want to introduce - and that's #432, an improvement to
I really appreciate the support of the 7 patrons on my Patreon