PostGraphile V5 release candidate! 🎉

After over 100 releases, PostGraphile V5 has finally reached release candidate status! 🎉 Assuming no issues are found, this software, these APIs, are what will make up the final PostGraphile v5.0 release! The runtime is ready, many of you are already using it in production, but the types and docs are a little behind. Help us get ready for release: try it out, tell us where the gaps are, and maybe help fill them!

Five years in the making, PostGraphile V5 raises the bar again

After a couple false starts, in February 2020 we kicked off the journey that would ultimately become PostGraphile V5 and the Grafast planning and execution engine. Since January 2023 we have shipped 38 pre-alpha, 20 alpha, and 49 beta releases. Every stage refined the ergonomics, uncovered tricky edge cases, and ultimately solved the four Grafast epics that blocked a stable release:

• ✅ Everything is batched, but “unary” values (variables, context, etc) are now treated as a special case.
• ✅ Early termination of field execution with a null now has first-class support.
• ✅ Plan-time “peeking” at runtime values is now forbidden, improving plan re-use.
• ✅ The exponential polymorphic branching hazard is now eradicated by converging before branching again.

The result is a platform that is faster, more expressive, more configurable, and easier to extend than anything we have shipped before.

Why this is still a release candidate

We do not anticipate breaking changes to the runtime behaviour. Numerous teams have already trusted beta builds in production for over a year and the feedback has been excellent. The remaining work is polish: verifying the docs, catching stray rough edges, and ensuring that migration guidance reflects the software as it exists today.

You can expect the occasional breaking change in TypeScript typings as we close gaps and fix inaccuracies. The runtime APIs will remain compatible, but you may need to adjust type annotations while we tighten things up. Likewise, some TSDoc comments are behind reality; we will update them alongside the docs.

If you bump into rough edges while trying V5, please raise an issue in the Crystal repo so we can address it before the final release.

Help us finish the documentation

The code moved faster than the words that describe it. Parts of the docs are out of date, others are missing, and a few contradict the behaviour you see in practice. We need review, issue reports, and small patches. Your first-hand notes about what is unclear are invaluable.

• Walk through the guides and flag inaccuracies.
• Suggest examples that clarify tricky concepts.
• Contribute short how-tos drawn from your own migration.
• Help us verify CLI reference pages against the current defaults.

Please open issues or pull requests and talk to us on Discord. We are prioritizing documentation and type improvements above new features during the RC period.

Try the release candidate today

Install the release candidate from npm; you should use the @rc tag with all of our modules to get the V5 version:

yarn add postgraphile@rc

You can also try the bundled CLI without installing (no tag needed here since it’s new!):

npx pgl -P pgl/amber -e -c postgres:///my_db -s public

Replace the connection string and schema with your own values.

Migrating from V4?

If you are upgrading from V4, follow the migration guide and let us know where it can be improved.

We’re particularly interested to hear how you get on, and what tools help with your migration. If you’re using AI code assistants, what instructions did you give? Can we clarify anything in the migration guide so they have greater success?

Thank you sponsors!

PostGraphile is crowd-funded open-source software. The sponsors listed on graphile.org have funded the years of work that brought us to this moment. If PostGraphile helps your team ship faster or run leaner infrastructure, please ask your company to become a sponsor so that we can keep investing in the project.