<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <id>https://postgraphile.withfri.day/news</id>
    <title>PostGraphile Blog</title>
    <updated>2026-10-28T02:00:00.000Z</updated>
    <generator>https://github.com/jpmonette/feed</generator>
    <link rel="alternate" href="https://postgraphile.withfri.day/news"/>
    <subtitle>PostGraphile Blog</subtitle>
    <icon>https://postgraphile.withfri.day/img/favicon.ico</icon>
    <entry>
        <title type="html"><![CDATA[PostGraphile V5.2 — A great time to upgrade!]]></title>
        <id>https://postgraphile.withfri.day/news/2026-10-28-v5.2-published</id>
        <link href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published"/>
        <updated>2026-10-28T02:00:00.000Z</updated>
        <summary type="html"><![CDATA[PostGraphile V5.2 brings major performance and type safety improvements following six months of refinement and production input.]]></summary>
        <content type="html"><![CDATA[<div class="intro_ohxd"><p>Six months ago we published PostGraphile V5: the culmination of several years' work redesigning almost every layer of the project, powered by the new Gra<em>fast</em> planning and execution engine. It was by far the biggest release in PostGraphile's history, bringing major improvements to performance, extensibility, maintainability and developer experience.</p><p>Since then, we've continued to refine V5 in response to feedback from early adopters and production deployments.</p><p>If you've been waiting to upgrade from V4, we think now is a great time!</p><h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="easy-upgrade">Easy upgrade<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#easy-upgrade" class="hash-link" aria-label="Direct link to Easy upgrade" title="Direct link to Easy upgrade" translate="no">​</a></h2><p>We have a <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4">V4 -&gt; V5 migration guide</a> available for those who have been waiting; the <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4#makev4preset"><code>makeV4Preset</code></a> means users can update to the new engine while keeping much of the V4 behavior.</p><p><strong>Now available: in collaboration with our sponsor Steelhead, we are making codemods available to sponsors to automate some of the work involved, see <a href="https://postgraphile.withfri.day/news/2026-10-28-codemods-early-access">V4→V5 codemods early access</a> for more detail and how to access them.</strong></p></div>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="six-months-of-refinement-with-production-input">Six months of refinement, with production input<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#six-months-of-refinement-with-production-input" class="hash-link" aria-label="Direct link to Six months of refinement, with production input" title="Direct link to Six months of refinement, with production input" translate="no">​</a></h2>
<p>Since V5.0 we've shipped a steady stream of improvements across PostGraphile and the underlying Gra<em>fast</em> engine. Among many smaller improvements were better planning performance for large schemas, fixes around subscriptions and watch mode, simpler <code>pgServices</code> configuration, and improved compatibility with more complex PostgreSQL schemas. The result is a noticeably more polished platform without changing the fundamental architecture that shipped in V5.</p>
<p>Today we're excited to announce PostGraphile 5.2 and Gra<em>fast</em> 1.2; this is a massive release, the culmination of <a href="https://github.com/graphile/crystal/pull/3127" target="_blank" rel="noopener noreferrer">3 months of work<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>. You can see <a href="https://github.com/graphile/crystal/releases" target="_blank" rel="noopener noreferrer">the changelogs<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> for full details, but we've attempted to summarize some of the key elements below:</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="performance">Performance<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#performance" class="hash-link" aria-label="Direct link to Performance" title="Direct link to Performance" translate="no">​</a></h3>
<ul>
<li class="">Users who were suffering performance regressions after moving to V5, rejoice! The cause was tracked down to poor PostgreSQL planning decisions caused by the combination of V5's new leaner SQL combined with suboptimal RLS policy design, and fixed through the use of materialized CTEs. <em>Remember: <a href="https://postgraphile.withfri.day/postgraphile/5/required-knowledge#writing-performant-rls-policies">don't pass row data to functions in RLS policies</a>, this is by far and away the most common reason that users suffer performance issues with RLS.</em></li>
<li class="">Database connections, roundtrips, and transactions have all been reduced by grouping similar SQL queries into the same PostgreSQL adaptor; this also made better use of prepared statements, yielding further speedups.</li>
<li class=""><code>PgSelectStep</code> now automatically deduplicates queries where possible, resulting in fewer roundtrips to the database.</li>
<li class=""><code>PgSelectStep</code> now automatically skips fetches when no rows can be returned due to <code>WHERE some_column = null</code> (which is always falsy).</li>
<li class=""><code>PgSelectStep</code> now switches from <code>left join</code> to subqueries when too many children request to be inlined. This reduces PostgreSQL planning time, and can also improve performance when poorly performing RLS policies are present.</li>
<li class="">A new experimental Gra<em>fast</em> <code>prepare()</code> method allows "warming" of plans before the server becomes available, avoiding planning pauses at runtime. This will be more impactful in a future release when we reduce plans’ retained memory (see “What’s next?”).</li>
<li class=""><code>connection()</code> no longer performs an unnecessary second database fetch for queries that didn't request row data, such as <code>someField(first: 1) { totalCount }</code>. Previously, it fetched the collection twice: once for the <code>totalCount</code> aggregate and once for the <code>first: 1</code> rows, even though those rows weren't needed.</li>
<li class="">PgSelectStep now allows developers to indicate whether a left join or subquery is preferred for a certain step, or children of that step, via the <code>setInliningStrategy(...)</code> and <code>setChildInliningStrategy(...)</code> methods.</li>
<li class="">Further optimizations throughout the stack.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="type-safety">Type safety<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#type-safety" class="hash-link" aria-label="Direct link to Type safety" title="Direct link to Type safety" translate="no">​</a></h3>
<ul>
<li class="">🌟<strong>New</strong>: <code>@graphile-pro/postgraphile</code> generates types from your database and GraphQL schema(s) to make plugin authoring a breeze: autocompletion in your editor, and type safety providing much stronger guardrails for agents. (<strong>Interested in early access? This is only available to Sponsors, <a href="https://postgraphile.withfri.day/contact">get in touch to get started</a>.</strong>)</li>
<li class="">Significant improvements to TypeScript types throughout.</li>
<li class=""><code>wrapPlans()</code> now receives the full <code>GraphileBuild.Build</code> type, rather than a partial type.</li>
<li class=""><code>build.getTypeMetaByName</code> now supports type narrowing on the <code>.kind</code> attribute, making <code>typeMeta.scope</code> strongly typed.</li>
<li class="">If you were assuming a Postgres record type was definitely a <code>PgSelectSingleStep</code>, you were assuming wrong… And might face planning failures under certain circumstances (typically relating to mutations). Use <code>PgClassSingleStep</code> instead, and we've added a helper in case not having a <code>PgSelectSingleStep</code> is causing you issues: <code>$record.toSelectSingle()</code>.</li>
<li class=""><code>PgResource.execute()</code> can now infer the result type from the function signature when available, rather than using the full union type.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="extensibility">Extensibility<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#extensibility" class="hash-link" aria-label="Direct link to Extensibility" title="Direct link to Extensibility" translate="no">​</a></h3>
<ul>
<li class="">The <code>PgInsertSingleStep</code>, <code>PgUpdateSingleStep</code> and <code>PgDeleteSingleStep</code> step classes now support an experimental <code>.wrap(...)</code> method allowing custom logic to run before and after an operation within the same transaction. This is particularly useful for <code>wrapPlans()</code> users.</li>
<li class="">Experimental support for type modifiers in PostgreSQL lays the groundwork for PostGIS and similar plugin expansion.</li>
<li class="">Higher quality support for custom Postgres adaptors: <code>GraphileConfig.DataplanPgClient</code> now reflects the chosen adaptor, including its custom methods/properties. This is particularly useful when writing custom <code>extendSchema()</code> or <code>wrapPlans()</code> plugins.</li>
<li class=""><code>orderByAscDesc</code> now supports providing a list of expressions.</li>
<li class="">More scope values added in various places to make schema extension easier.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="ergonomics">Ergonomics<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#ergonomics" class="hash-link" aria-label="Direct link to Ergonomics" title="Direct link to Ergonomics" translate="no">​</a></h3>
<ul>
<li class=""><code>addPgTableCondition</code> and <code>addPgTableOrderBy</code> now support a more ergonomic expression of the target: <code>"my_schema.my_table"</code> rather than <code>{schemaName: "my_schema", tableName: "my_table"}</code>. This target also benefits from autocompletion and type checking for users of <code>@graphile-pro/postgraphile</code> type generation.</li>
<li class=""><a href="https://grafast.org/grafast/standard-steps/multistep/" target="_blank" rel="noopener noreferrer">Multistep<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> syntax, which is often more efficient than passing <code>object({...})</code> or <code>list([...])</code> to certain steps, is now supported in more places.</li>
<li class="">New <code>PgExecutor.executePositional</code> and <code>PgExecutor.executeNamed</code> variants of the execute method offer better ergonomics.</li>
<li class="">Certain patterns of user planning code that might lead to deadlock are now blocked up front.</li>
<li class="">GraphQL schema ordering is now slightly more stable.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="fixes">Fixes<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#fixes" class="hash-link" aria-label="Direct link to Fixes" title="Direct link to Fixes" translate="no">​</a></h3>
<ul>
<li class=""><code>PgUpdateSingleStep</code> no longer throws an error when no values are provided for an update; instead it simply exits having changed no rows.</li>
<li class="">Gra<em>fast</em> now handles inhibited steps more reliably, preventing over-inhibition, particularly in relation to custom <code>sideEffect()</code> steps.</li>
<li class="">Various fixes to V4 compatibility.</li>
<li class="">Various minor fixes and improvements including marking up more plugins for ordering, fixes to some smart tag behaviors, fixes to some descriptions in the GraphQL schema, and support for empty PostgreSQL ranges, etc</li>
</ul>
<p>For more details, see the <a href="https://github.com/graphile/crystal/blob/main/postgraphile/postgraphile/CHANGELOG.md#520" target="_blank" rel="noopener noreferrer">PostGraphile V5.2 changelog<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> and <a href="https://github.com/graphile/crystal/blob/main/grafast/grafast/CHANGELOG.md#120" target="_blank" rel="noopener noreferrer">Gra<em>fast</em> V1.2 changelog<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="help-us-improve-v5-dx-and-performance">Help us improve V5 DX and performance<a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published#help-us-improve-v5-dx-and-performance" class="hash-link" aria-label="Direct link to Help us improve V5 DX and performance" title="Direct link to Help us improve V5 DX and performance" translate="no">​</a></h2>
<p>We don't normally reveal our roadmap, but we are sharing that our next focus is going to be on reducing memory usage of PostGraphile V5 and Gra<em>fast</em>. With the launch of V5 we've successfully offloaded a lot of the work from the database to the JS layer, helping you scale further; but the JS layer is a lot more memory hungry than it needs to be, and we have plans to fix this.</p>
<p>How much of an improvement we can make really depends on how much support we get. A couple of our sponsors have put forward an investment into this work, funding the reduction of memory usage by introspection, and reducing the memory usage of retained Gra<em>fast</em> plans. <strong>Their funding gives us a starting point, and we’re looking for more sponsors to help us take this work further.</strong></p>
<p>With additional funding, we could extend the work to include:</p>
<ul>
<li class="">Improving startup time of the PostGraphile process, particularly relevant to development experience and CI duration/agent loop delays.</li>
<li class="">Improving the exported executable schema, particularly relevant to folks running PostGraphile in serverless environments</li>
<li class="">Further reducing memory usage and improving performance.</li>
<li class="">Enabling new capabilities, such as performing operation planning off of the main runloop to reduce runloop stalls and the related latency impact.</li>
</ul>
<p>The scope of this additional work will depend on the funding we receive. If your business would benefit from these improvements, please get in touch, or <a href="https://github.com/sponsors/benjie" target="_blank" rel="noopener noreferrer">sponsor us/make a one-off contribution via GitHub Sponsors<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>.</p>
<div class="text--center"><a class="button button--primary button--lg" href="https://postgraphile.withfri.day/contact">Get in contact to donate to the crowdfund</a></div>
<figure><p><img decoding="async" loading="lazy" alt="Thank you" src="https://postgraphile.withfri.day/assets/images/thank-you-c179c9ed75281d45ea6a8993ab3d0f59.svg" width="239" height="300" class="img_ev3q"></p></figure>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <author>
            <name>Jem</name>
            <uri>https://bsky.app/profile/jem.graphile.org</uri>
        </author>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[V4→V5 codemods early access]]></title>
        <id>https://postgraphile.withfri.day/news/2026-10-28-codemods-early-access</id>
        <link href="https://postgraphile.withfri.day/news/2026-10-28-codemods-early-access"/>
        <updated>2026-10-28T01:00:00.000Z</updated>
        <content type="html"><![CDATA[<div class="intro_ohxd"><p>One of the design goals of V5 was that you shouldn't have to adopt every new idea on day one.</p><p>The <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4#makev4preset"><code>makeV4Preset</code></a> already allowed users to move onto the new engine while keeping much of their V4 behavior. Once using the preset and comfortable with V5, users could gradually adopt the new defaults and features at their own pace, or just stick with the V4 behaviors.
For database-centric users this meant a near identical schema with minimal work; but there are deployments out there that use custom plugins… sometimes a lot of custom plugins.</p><p>We're pleased to announce that codemods are now available to give those users a helping hand.</p></div>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="sponsor-only-early-access-to-codemods">Sponsor only early access to codemods<a href="https://postgraphile.withfri.day/news/2026-10-28-codemods-early-access#sponsor-only-early-access-to-codemods" class="hash-link" aria-label="Direct link to Sponsor only early access to codemods" title="Direct link to Sponsor only early access to codemods" translate="no">​</a></h2>
<p>Alongside the <a href="https://postgraphile.withfri.day/news/2026-10-28-v5.2-published">release of V5.2</a> we're giving sponsors early access to MIT-licensed codemods that automate some of the work involved in upgrading your codebase from V4 to V5. These codemods perform a lot of mechanical restructuring, but they also fix a number of bad patterns and N+1s that were common in V4 extend schema plugins (typically due to limitations of the V4 platform itself) by rewriting the logic into more efficient Gra<em>fast</em> plan resolvers which are always batched.</p>
<p>These codemods will not normally result in full migration, but they will do the majority of the work for you in a deterministic way, reducing the amount of time you (or your agents) need to spend on updating significantly.</p>
<p>This project is thanks primarily to one of our long-standing sponsors, Steelhead, who found the codemods were pivotal for the transition of their well-established production codebase to PostGraphile V5. We’d like to thank Steelhead for sponsoring this work and allowing us to turn tooling developed for a real migration into something the wider community can benefit from. Sponsors can have access to these codemods today in the Graphile sponsors-only GitHub repository, we plan to make them publicly available once we have had time to improve their documentation and smooth any rough edges.</p>
<p>Normally we review every line of code, but the codemods being a one-time code transformer with almost no I/O (jscodeshift handles that, mostly) meant that we were not so concerned about security or performance ramifications (a quick scan could determine nothing funky was going on), allowing us to expand the codemods beyond what we could normally build limited by the time intensive act of code review. This is compensated for by the vast array of test cases, so when running the codemods against your own codebase we recommend extending the tests with any problematic patterns from your own codebase and having your agent update the codemods to match. You’ll then need to replay the codemods from clean again, they aren’t designed to run twice in a row.</p>
<p>Once the codemods complete, commit the changes and an agent should be able to help you tidy up the rough edges and get your PR passing again. One reason to perform this transition with codemods rather than agents is that the codemods are deterministic, replayable (e.g. on rebase), and are governed by my own preferences and insights of how code should be transformed, allowing you to benefit from more of the V5 improvements such as batching and more straightforward code.</p>
<p>Between the codemods, the migration guide, and six months of real-world experience behind the release, upgrading to V5 is even smoother today than it was on launch day. But, if you need help, guidance, a code pair, or even to outsource the work to the experts, we have a range of support options available: from a single call right up to a support and development contract. <a href="https://postgraphile.withfri.day/contact">Get in touch</a>, we’d love to hear from you.</p>
<div class="text--center"><a class="button button--primary button--lg" href="https://postgraphile.withfri.day/sponsor">Sponsor Graphile to get started</a></div>
<p><em>If you already sponsor and want access to the sponsors-only repository, <a href="https://postgraphile.withfri.day/contact">get in contact via email or Discord</a></em>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="help-us-improve-v5-dx-and-performance">Help us improve V5 DX and performance<a href="https://postgraphile.withfri.day/news/2026-10-28-codemods-early-access#help-us-improve-v5-dx-and-performance" class="hash-link" aria-label="Direct link to Help us improve V5 DX and performance" title="Direct link to Help us improve V5 DX and performance" translate="no">​</a></h2>
<p>The codemods are one example of how sponsor-funded work can benefit the wider PostGraphile community. Our next focus is another: reducing the memory usage of PostGraphile V5 and Gra<em>fast</em>.</p>
<p>With the launch of V5 we've successfully offloaded a lot of the work from the database to the JS layer, helping you scale further; but the JS layer is a lot more memory hungry than it needs to be, and we have plans to fix this.</p>
<p>How much of an improvement we can make really depends on how much support we get. A couple of our sponsors have put forward an investment into this work, funding the reduction of memory usage by introspection, and reducing the memory usage of retained Grafast plans. With your help, we should be able to expand these improvements to cover related work including:</p>
<ul>
<li class="">Improving startup time of the PostGraphile process, particularly relevant to development experience and CI duration/agent loop delays.</li>
<li class="">Improving the exported executable schema, particularly relevant to folks running PostGraphile in serverless environments</li>
<li class="">Further reducing memory usage and improving performance.</li>
<li class="">Enabling new capabilities, such as performing operation planning off of the main runloop to reduce runloop stalls and the related latency impact.</li>
</ul>
<div class="text--center"><a class="button button--primary button--lg" href="https://postgraphile.withfri.day/contact">Get in contact to donate to the crowdfund</a></div>
<figure><p><img decoding="async" loading="lazy" alt="Thank you" src="https://postgraphile.withfri.day/assets/images/thank-you-c179c9ed75281d45ea6a8993ab3d0f59.svg" width="239" height="300" class="img_ev3q"></p></figure>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <author>
            <name>Jem</name>
            <uri>https://bsky.app/profile/jem.graphile.org</uri>
        </author>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[Power, Performance, Productivity; PostGraphile V5 Published!]]></title>
        <id>https://postgraphile.withfri.day/news/2026-03-24-v5-published</id>
        <link href="https://postgraphile.withfri.day/news/2026-03-24-v5-published"/>
        <updated>2026-03-24T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[PostGraphile V5 is a ground-up re-architecture with significant enhancements to capability, customizability, extensibility, flexibility, maintainability, performance, and correctness — the result of several years of design, experimentation, and real-world production feedback — while staying true to PostGraphile’s key goal: implementing the obvious so you only write code that delivers true value.]]></summary>
        <content type="html"><![CDATA[<div class="intro_ohxd"><p>PostGraphile Version 5 is a ground-up re-architecture with significant enhancements
to capability, customizability, extensibility, flexibility, maintainability,
performance, and correctness — the result of several years of design, experimentation, and real-world
production feedback — whilst staying true to PostGraphile’s key goal: <strong>implementing the obvious so you
only write code that delivers true value</strong>.</p><p>Try it now:</p><div class="language-shell codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-shell codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">npx pgl </span><span class="token parameter variable" style="color:#36acaa">-P</span><span class="token plain"> pgl/amber </span><span class="token parameter variable" style="color:#36acaa">-e</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">-c</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">'postgres:///mydb'</span><br></div></code></pre></div></div><p>We want to extend our sincere thanks to every person, company and organization
that has sponsored us throughout the lifetime of the PostGraphile project, and
extend a special thanks to the Featured Sponsors who helped support many of the
key efforts during the PostGraphile V5 and Gra<em>fast</em> development effort: <strong>The
Guild, Dovetail, Steelhead, Surge, Netflix, StoryScript, Chad Furman, Fanatics,
Enzuzo and Accenture</strong>.</p></div>
<!-- -->
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-rewrite-why">A rewrite? Why?<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#a-rewrite-why" class="hash-link" aria-label="Direct link to A rewrite? Why?" title="Direct link to A rewrite? Why?" translate="no">​</a></h2>
<p>With GraphQL resolvers having proven to be a performance limitation for PostGraphile Version 3, Version 4 was based around a “lookahead” system. This system grew organically, from a proof of concept built in just a couple weeks, to a production dependency used under sustained pressure by many around the world. It ended up delivering power and performance, but also complexity and limitations.</p>
<p><strong>PostGraphile isn’t meant to simply expose a database over GraphQL.</strong> It should handle the drudgery, eliminating unnecessary work for common needs, whilst remaining sufficiently flexible that you can design the exact GraphQL schema that your frontend developers need. Broadly, it has achieved this; but over the past 7 years of PostGraphile V4 being our stable release, we’ve found that the effort required for schema customization was not as minimal as we’d like, and the main issue behind this has been the lookahead system.</p>
<p>Recognizing that our lookahead system had just been a first attempt at fixing a fundamental issue with GraphQL’s resolver-based execution model, we put our thinking caps on and ultimately invented Gra<em>fast</em>…</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="new-execution-engine">New execution engine<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#new-execution-engine" class="hash-link" aria-label="Direct link to New execution engine" title="Direct link to New execution engine" translate="no">​</a></h2>
<p>Gra<em>fast</em> eschews the previous techniques of resolvers and lookahead, instead taking a radically new approach to GraphQL execution.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="plan-resolvers-steps-and-dataflow">Plan resolvers, steps and dataflow<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#plan-resolvers-steps-and-dataflow" class="hash-link" aria-label="Direct link to Plan resolvers, steps and dataflow" title="Direct link to Plan resolvers, steps and dataflow" translate="no">​</a></h3>
<p>When a request comes in, before any fetching or execution takes place, a plan consisting of execution steps and dataflow between them is determined from synchronous “plan resolvers” attached to each field. Plan resolvers were designed from the start to be ergonomic, with a minimal learning curve similar to that of React hooks. Here you can see how traditional resolver concepts map to plan resolvers:</p>
<figure><p><img decoding="async" loading="lazy" alt="Code for a resolver on the left, code for a plan resolver on the right. The code for a plan resolver looks similar to a basic GraphQL resolver, but the key difference is a plan resolver shows how to get the data, not just an instruction to get the data." src="https://postgraphile.withfri.day/assets/images/2026-03-plan-resolvers-f89c4dbb1e0128a6edc4d22461942cd2.png" width="960" height="540" class="img_ev3q"></p></figure>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="batched-execution-and-plan-re-use">Batched execution and plan re-use<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#batched-execution-and-plan-re-use" class="hash-link" aria-label="Direct link to Batched execution and plan re-use" title="Direct link to Batched execution and plan re-use" translate="no">​</a></h3>
<p>Once established, the plan is optimized: redundant work eliminated, related work combined, and individual steps honed to only perform necessary work. Finally, the plan is executed — with batch execution to eliminate the N+1 problem by design — and if that same operation is seen again (even with different variables/context) the plan can be reused, eliminating the per-request AST traversal costs we had with the lookahead system.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="seamless-extension-and-reduced-database-load">Seamless extension and reduced database load<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#seamless-extension-and-reduced-database-load" class="hash-link" aria-label="Direct link to Seamless extension and reduced database load" title="Direct link to Seamless extension and reduced database load" translate="no">​</a></h3>
<p>You can read more about this new engine and the key concepts behind it in the <a href="https://grafast.org/news/2026-03-24-v1-released" target="_blank" rel="noopener noreferrer">Grafast V1.0 release announcement<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>, but for PostGraphile it enables significant improvements:</p>
<ul>
<li class="">PostGraphile can perform a lot more optimizations in JS-land, reducing SQL complexity and execution time, and more importantly moving work from the hard-to-scale database tier to the easy-to-scale JS tier.</li>
<li class="">Due to the above, connections are now a lot more performant, almost matching simple lists for efficiency when used equivalently.</li>
<li class="">Plan resolvers for custom fields and types means you can blend PostGraphile’s autogenerated logic with your custom extensions seamlessly, and without any of the arcane incantations or N+1 issues of the past.</li>
<li class="">Greater control over optimization: you can instruct PostGraphile <em>not</em> to inline SQL into parent queries in certain positions.</li>
<li class="">Evolution is easier: should one of your types need re-architecting in the database, you can easily replace that type’s logic in the schema with your own custom code, without having to re-write dependent plan resolvers.</li>
<li class="">Abstract types are now supported! (<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#native-support-for-abstract-types">see below</a>)</li>
</ul>
<p>And since we had to rebuild PostGraphile on top of Gra<em>fast</em> anyway, we figured why not fix “a few” other things whilst we were at it? You can read a pretty big list of changes in our <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4/v5-new-feature-summary">V5 New Feature Summary</a>, but here’s some highlights!</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="executable-schema-exports">Executable schema exports<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#executable-schema-exports" class="hash-link" aria-label="Direct link to Executable schema exports" title="Direct link to Executable schema exports" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="an-eject-button">An “eject” button<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#an-eject-button" class="hash-link" aria-label="Direct link to An “eject” button" title="Direct link to An “eject” button" translate="no">​</a></h3>
<p>Adopting PostGraphile is no longer a semi-permanent decision; now you can export your schema as executable code and take over maintenance of it whenever you want — like an “eject” button! Thanks to Gra<em>fast</em>’s straightforward plan resolvers, the exported code is easy to comprehend and you get to keep PostGraphile’s incredible performance even whilst customizing the schema to your heart’s content!</p>
<p>Graphile has always had a soft spot for entrepreneurs, we aim to help you get your projects from ideation to production deployment with minimal infrastructure and complexity, and many PostGraphile and Graphile Worker users have raised multiple rounds of funding using our software to power their backends. But there’s always the concern: what happens when I outgrow PostGraphile? Now the answer is simple: eject!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="incredibly-fast-startup-in-serverless">Incredibly fast startup in serverless<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#incredibly-fast-startup-in-serverless" class="hash-link" aria-label="Direct link to Incredibly fast startup in serverless" title="Direct link to Incredibly fast startup in serverless" translate="no">​</a></h3>
<p>Executable schema exports are also the recommended way to run a PostGraphile schema on serverless environments such as AWS Lambda — no database introspection, no plugin system, no huge dependency graph; just the SDL for your schema, its plan resolvers and their runtime dependencies such as <code>graphql</code>, <code>grafast</code> and <code>@dataplan/pg</code>. No runtime dependencies on PostGraphile or the Graphile Build system!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="aids-understanding">Aids understanding<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#aids-understanding" class="hash-link" aria-label="Direct link to Aids understanding" title="Direct link to Aids understanding" translate="no">​</a></h3>
<p>If you want to understand what PostGraphile is doing so you can more easily customize it… export the schema and have a read!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="improvements-to-come">Improvements to come<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#improvements-to-come" class="hash-link" aria-label="Direct link to Improvements to come" title="Direct link to Improvements to come" translate="no">​</a></h3>
<p>Executable schema exports is one of the features we’re most excited about — we’d love to hear your input! Right now the output is in pretty good shape but could always be better; one of the recent release candidates massively decreased the size of the exported code without any negative impact on runtime performance, but there’s still more that can be done.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="native-support-for-abstract-types">Native support for abstract types<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#native-support-for-abstract-types" class="hash-link" aria-label="Direct link to Native support for abstract types" title="Direct link to Native support for abstract types" translate="no">​</a></h2>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>What is an abstract type?</div><div class="admonitionContent_BuS1"><p>Abstract types are used in GraphQL to indicate a position that can be one of a set of different types. For example a field might state it will return a <code>Pet</code>, but at runtime that must actually be a <code>Cat</code> or a <code>Dog</code>. In GraphQL there are two abstract output types: <code>interface</code> for types that share a common interface (i.e. certain fields they must support), and <code>union</code> for types that don’t.</p></div></div>
<p>Thanks to Gra<em>fast</em>, PostGraphile V5 was able to add support for a number of polymorphism patterns in your PostgreSQL database, including:</p>
<ul>
<li class="">
<p>“Single table” polymorphism, where a single table (<code>pets</code>) represents multiple concrete datatypes (<code>Cat</code>, <code>Dog</code>, <code>Fish</code>) via a <code>type</code> column</p>
</li>
<li class="">
<p>“Relational” polymorphism, where a central table (<code>pets</code>) represents an interface and stores the shared attributes, and a per-type table (<code>cats</code>) is one-to-one joined and provides the additional columns for that type</p>
</li>
<li class="">
<p>“Union” polymorphism, where independent tables indicate that they either share the same common interface type, or that they all belong to the same union.</p>
</li>
</ul>
<p>We’d like to extend a special thank you to <a href="https://netflix.com/" target="_blank" rel="noopener noreferrer">Netflix<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> for working with us on developing the polymorphism patterns seen in PostGraphile V5, their real-world needs and help iterating ensured that the solutions we were adding solved real problems. Their identification and diagnosis of issues in early prototypes ultimately lead to significant improvements to Gra<em>fast</em> itself.</p>
<p>Abstract type support in PostGraphile gives you more flexibility in modelling complex systems in ways that feel ergonomic to frontend consumers whilst retaining significant flexibility of implementation on the backend.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ruru-the-new-postgraphiql">Ruru: the new PostGraphiQL<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#ruru-the-new-postgraphiql" class="hash-link" aria-label="Direct link to Ruru: the new PostGraphiQL" title="Direct link to Ruru: the new PostGraphiQL" translate="no">​</a></h2>
<p>“PostGraphiQL” was V4’s integrated version of GraphiQL, making it easy for users to get started writing GraphQL queries. In V5 we’ve broken this out into its own standalone package — Ruru — and given it a lot of extra capabilities including the ability to visualize the Gra<em>fast</em> query plan! We hope you’ll find it Reliable, Up-to-date, Relevant and Useful!</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="standardized-plugins-and-shareable-configuration">Standardized plugins and shareable configuration<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#standardized-plugins-and-shareable-configuration" class="hash-link" aria-label="Direct link to Standardized plugins and shareable configuration" title="Direct link to Standardized plugins and shareable configuration" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="your-schema-should-serve-frontend-needs">Your schema should serve frontend needs<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#your-schema-should-serve-frontend-needs" class="hash-link" aria-label="Direct link to Your schema should serve frontend needs" title="Direct link to Your schema should serve frontend needs" translate="no">​</a></h3>
<p>Customizability and extensibility are at the heart of PostGraphile — your GraphQL schema should not be a simple reflection of your database schema, but something that truly serves frontend needs. In PostGraphile almost every element of your schema is handled via a plugin: from database introspection, through to adding relations, and even pagination arguments!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="unified-pluginpreset-system">Unified plugin/preset system<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#unified-pluginpreset-system" class="hash-link" aria-label="Direct link to Unified plugin/preset system" title="Direct link to Unified plugin/preset system" translate="no">​</a></h3>
<p>In V4 we had two separate plugin systems: one for the GraphQL schema, and one introduced after release to handle the wider concerns of request handling, CLI and so on. These two plugin systems caused a lot of user confusion, not least because there was different usage instructions depending on if you were using PostGraphile through its CLI server, through the “library mode” (middleware), or in “schema only” mode (for SSR/backend tasks).</p>
<p>In V5 we’ve introduced a “plugin and preset” system called <code>graphile-config</code> that takes everything we learned about plugins across all our various projects and combines it into a single system. Now a single configuration object, a “preset”, can be shared across all of your usages of PostGraphile: CLI, library and schema-only and more…</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="new-debug-tooling">New debug tooling<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#new-debug-tooling" class="hash-link" aria-label="Direct link to New debug tooling" title="Direct link to New debug tooling" translate="no">​</a></h3>
<p>These configuration files can be read by command-line utilities such as the new <code>graphile</code> command which can be used to help debug, whether this be <code>graphile config print</code> to see your fully resolved configuration with all the plugins and options, or <code>graphile behavior debug</code> to determine why certain database elements are (or are not) exposed in your GraphQL schema. (We’ve also integrated <code>graphile-config</code> into some of our other projects such as our job queue Graphile Worker and our GraphQL document rules enforcer gqlcheck.)</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="sharing-a-core-preset-across-instances">Sharing a core preset across instances<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#sharing-a-core-preset-across-instances" class="hash-link" aria-label="Direct link to Sharing a core preset across instances" title="Direct link to Sharing a core preset across instances" translate="no">​</a></h3>
<p>This is particularly useful if you run multiple PostGraphile instances: you can create a shared preset with the common configuration, and then “extend” it with custom per-instance configuration options/plugin addition or removal.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="overhauled-types">Overhauled types<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#overhauled-types" class="hash-link" aria-label="Direct link to Overhauled types" title="Direct link to Overhauled types" translate="no">​</a></h3>
<p>Plugins are also much easier to write, with a declarative shape that aids discoverability and the ability for each plugin to augment the types it impacts, improving type safety and making plugins easier to write, safer to maintain, and more resilient as your project evolves.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="and-so-much-more">And so much more…<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#and-so-much-more" class="hash-link" aria-label="Direct link to And so much more…" title="Direct link to And so much more…" translate="no">​</a></h2>
<p>The <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4/v5-new-feature-summary">V5 new features page</a> covers many more of the enhancements we’ve added over the past 5 years, including: upgrading <code>@omit</code> to the behavior system, a Relay preset, massively improved types, no more <code>RETURNING *</code>, write-only columns, JOINs, DB connection can now be on-demand, the ability to override the Postgres client on a per-request basis, <a href="https://nodejs.org/" target="_blank" rel="noopener noreferrer">Node.js<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> webserver framework integrations overhaul, improved database index behaviors, reflect multiple Postgres DBs, database-schema-based multi-tenancy via “unqualified” tables/functions, Postgres client adaptor system, plugin ordering is now less important, easier inflection overrides, deleting a field deletes the plan (unlike V4’s mess!), and more…</p>
<p>We’ve spent 5 years building it, so it might take you a little while to work your way through… Suffice to say, there’s barely a single feature in PostGraphile that the V5 work hasn’t enhanced or improved in some way!</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="designed-for-the-long-term">Designed for the long term<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#designed-for-the-long-term" class="hash-link" aria-label="Direct link to Designed for the long term" title="Direct link to Designed for the long term" translate="no">​</a></h2>
<p>V5 is designed to scale much further with you, and to let you “eject” if and when it can’t keep up any more. There’s a lot more capability for customization, optimization and enhancement, and space to iterate to cover more user needs. The preset system lets us change defaults and experience for new users whilst supporting existing users without requiring breaking changes. Database efficiency is massively improved, with work offloaded from the database to the easier to scale JS layer; but more importantly the Gra<em>fast</em> planning system allows us to iterate with alternative optimization strategies without needing <em>any</em> changes to user-written or autogenerated plan resolver code.</p>
<p><strong>PostGraphile V5 is designed to help you move fast early on, with minimal infrastructure and lightning fast iteration time; grow with you as you find product-market fit, scaling and shaping your API to serve the needs of your growing business; and step out of the way when it no longer serves your needs, without penalty or painful rewrites</strong>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="migrating-from-v4-to-v5">Migrating from V4 to V5<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#migrating-from-v4-to-v5" class="hash-link" aria-label="Direct link to Migrating from V4 to V5" title="Direct link to Migrating from V4 to V5" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="v4-preset-and-migration-walk-through">V4 preset and migration walk-through<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#v4-preset-and-migration-walk-through" class="hash-link" aria-label="Direct link to V4 preset and migration walk-through" title="Direct link to V4 preset and migration walk-through" translate="no">​</a></h3>
<p>We’ve prepared a “V4 Preset” that smooths the process of migration from V4 to V5 by restoring older behaviors and fields, and a <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4">migration guide</a> that walks you through the necessary changes.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="minimal-effort-for-database-first-users">Minimal effort for database-first users<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#minimal-effort-for-database-first-users" class="hash-link" aria-label="Direct link to Minimal effort for database-first users" title="Direct link to Minimal effort for database-first users" translate="no">​</a></h3>
<p>If your PostGraphile V4 setup doesn’t use any custom plugins then migration should be very straightforward; there are a couple of minor breaking changes relating to field nullability (correctness fixes) but this will not break the majority of apps and you can even undo those if you wish. We’ve already ported a number of the community plugins to be compatible with V5, but some are still pending.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="plugin-migration-codemods-underway">Plugin migration codemods underway<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#plugin-migration-codemods-underway" class="hash-link" aria-label="Direct link to Plugin migration codemods underway" title="Direct link to Plugin migration codemods underway" translate="no">​</a></h3>
<p>For users with custom plugins, effort may be larger. Thanks to a collaboration with <a href="https://gosteelhead.com/" target="_blank" rel="noopener noreferrer">Steelhead<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> we are working on codemods to ease migration and hope to open-source them soon. If you’d like to help support this effort, please reach out.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="already-in-production">Already in production<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#already-in-production" class="hash-link" aria-label="Direct link to Already in production" title="Direct link to Already in production" translate="no">​</a></h3>
<p>V5 is already used in production by many people, for some it has been that way for over a year! The extended alpha, beta, and RC phases have given us the time to hone our APIs and give great confidence in the software we’re making available today.</p>
<p>We hope you enjoy PostGraphile V5, and we’re excited to see what you build with it!</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="sponsors-make-postgraphile-possible">Sponsors make PostGraphile possible<a href="https://postgraphile.withfri.day/news/2026-03-24-v5-published#sponsors-make-postgraphile-possible" class="hash-link" aria-label="Direct link to Sponsors make PostGraphile possible" title="Direct link to Sponsors make PostGraphile possible" translate="no">​</a></h2>
<p>PostGraphile is crowd-funded open-source software, relying on sponsorship from individuals and companies to keep advancing.</p>
<p>If your employer benefits from PostGraphile, Gra<em>fast</em>, or the wider Graphile suite, please encourage them to fund our work. Our software saves companies substantial time and money by reducing development effort and running costs. Sponsorship is an investment in your product’s future, ensuring the foundations of your software stack remain secure and reliable for years to come.</p>
<p>Find out more about sponsorship at <a href="https://graphile.org/sponsor" target="_blank" rel="noopener noreferrer">graphile.org/sponsor<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></p>
<figure><p><img decoding="async" loading="lazy" alt="Thank you" src="https://postgraphile.withfri.day/assets/images/thank-you-c179c9ed75281d45ea6a8993ab3d0f59.svg" width="239" height="300" class="img_ev3q"></p></figure>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <author>
            <name>Jem</name>
            <uri>https://bsky.app/profile/jem.graphile.org</uri>
        </author>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[PostGraphile V5 release candidate! 🎉]]></title>
        <id>https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate</id>
        <link href="https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate"/>
        <updated>2025-10-28T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[The code is done, the docs and types need some love. Help us prepare for the release of PostGraphile V5!]]></summary>
        <content type="html"><![CDATA[<div class="intro_ohxd"><p>After over 100 releases, PostGraphile V5
has finally reached <strong>release candidate</strong> 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!</p></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="five-years-in-the-making-postgraphile-v5-raises-the-bar-again">Five years in the making, PostGraphile V5 raises the bar again<a href="https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate#five-years-in-the-making-postgraphile-v5-raises-the-bar-again" class="hash-link" aria-label="Direct link to Five years in the making, PostGraphile V5 raises the bar again" title="Direct link to Five years in the making, PostGraphile V5 raises the bar again" translate="no">​</a></h2>
<p>After a couple false starts, in February 2020 we kicked off the journey that
would ultimately become PostGraphile V5 and the <a href="https://grafast.org/" target="_blank" rel="noopener noreferrer">Gra<em>fast</em> planning and execution
engine<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>. 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 Gra<em>fast</em> epics that blocked a
stable release:</p>
<ul>
<li class="">✅ Everything is batched, but “unary” values (variables, context, etc) are now treated as a special case.</li>
<li class="">✅ Early termination of field execution with a <code>null</code> now has first-class
support.</li>
<li class="">✅ Plan-time “peeking” at runtime values is now forbidden, improving plan
re-use.</li>
<li class="">✅ The exponential polymorphic branching hazard is now eradicated by
converging before branching again.</li>
</ul>
<p>The result is a platform that is faster, more expressive, more configurable, and
easier to extend than anything we have shipped before.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-this-is-still-a-release-candidate">Why this is still a release candidate<a href="https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate#why-this-is-still-a-release-candidate" class="hash-link" aria-label="Direct link to Why this is still a release candidate" title="Direct link to Why this is still a release candidate" translate="no">​</a></h2>
<p>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.</p>
<p>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.</p>
<p>If you bump into rough edges while trying V5, please raise an issue in the
<a href="https://github.com/graphile/crystal" target="_blank" rel="noopener noreferrer">Crystal repo<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> so we can address it before
the final release.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="help-us-finish-the-documentation">Help us finish the documentation<a href="https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate#help-us-finish-the-documentation" class="hash-link" aria-label="Direct link to Help us finish the documentation" title="Direct link to Help us finish the documentation" translate="no">​</a></h2>
<p>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.</p>
<ul>
<li class="">Walk through the guides and flag inaccuracies.</li>
<li class="">Suggest examples that clarify tricky concepts.</li>
<li class="">Contribute short how-tos drawn from your own migration.</li>
<li class="">Help us verify CLI reference pages against the current defaults.</li>
</ul>
<p>Please <a href="https://github.com/graphile/crystal" target="_blank" rel="noopener noreferrer">open issues or pull requests<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> and
talk to us on <a href="https://discord.gg/graphile" target="_blank" rel="noopener noreferrer">Discord<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>. We are prioritizing
documentation and type improvements above new features during the RC period.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="try-the-release-candidate-today">Try the release candidate today<a href="https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate#try-the-release-candidate-today" class="hash-link" aria-label="Direct link to Try the release candidate today" title="Direct link to Try the release candidate today" translate="no">​</a></h2>
<p>Install the release candidate from npm; you should use the <code>@rc</code> tag with all of
our modules to get the V5 version:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">yarn</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">add</span><span class="token plain"> postgraphile@rc</span><br></div></code></pre></div></div>
<p>You can also try the bundled CLI without installing (no tag needed here since
it’s new!):</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">npx pgl </span><span class="token parameter variable" style="color:#36acaa">-P</span><span class="token plain"> pgl/amber </span><span class="token parameter variable" style="color:#36acaa">-e</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">-c</span><span class="token plain"> postgres:///my_db </span><span class="token parameter variable" style="color:#36acaa">-s</span><span class="token plain"> public</span><br></div></code></pre></div></div>
<p>Replace the connection string and schema with your own values.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="migrating-from-v4">Migrating from V4?<a href="https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate#migrating-from-v4" class="hash-link" aria-label="Direct link to Migrating from V4?" title="Direct link to Migrating from V4?" translate="no">​</a></h2>
<p>If you are upgrading from V4, follow the <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4">migration
guide</a> and let us know where it can be
improved.</p>
<p>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?</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-sponsors">Thank you sponsors!<a href="https://postgraphile.withfri.day/news/2025-10-28-v5-release-candidate#thank-you-sponsors" class="hash-link" aria-label="Direct link to Thank you sponsors!" title="Direct link to Thank you sponsors!" translate="no">​</a></h2>
<p>PostGraphile is crowd-funded open-source software. The sponsors listed on
<a href="https://graphile.org/sponsor" target="_blank" rel="noopener noreferrer">graphile.org<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> 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.</p>
<figure><p><img decoding="async" loading="lazy" alt="Thank you" src="https://postgraphile.withfri.day/assets/images/thank-you-c179c9ed75281d45ea6a8993ab3d0f59.svg" width="239" height="300" class="img_ev3q"></p></figure>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <author>
            <name>Jem</name>
            <uri>https://bsky.app/profile/jem.graphile.org</uri>
        </author>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[Last epic solved!]]></title>
        <id>https://postgraphile.withfri.day/news/2025-06-07-last-epic-solved</id>
        <link href="https://postgraphile.withfri.day/news/2025-06-07-last-epic-solved"/>
        <updated>2025-06-07T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[Polymorphism overhauled for greater efficiency and ergonomics. This is the last breaking change to plan resolvers we are expecting for v1.]]></summary>
        <content type="html"><![CDATA[<div class="intro_ohxd"><p>In the first Gra<em>fast</em> Working Group, we outlined 4 <em>major</em> issues in Gra<em>fast</em>
that needed to be addressed before we could think about general release. The fourth, and final,
epic has now been solved!</p><ul>
<li class="">✅ Global dependencies — solved via “unary” steps</li>
<li class="">✅ Early exit — solved via “flags”</li>
<li class="">✅ Eradicating eval</li>
<li class="">✅ <strong>Polymorphism — this release!</strong></li>
</ul></div>
<p>Gra<em>fast</em> is the cutting-edge GraphQL planning and execution engine which PostGraphile
uses, allowing it to build much more efficient SQL queries than PostGraphile V4 could
achieve, whilst also significantly expanding the capabilities of the system - not to
mention solving some longstanding issues!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="polymorphism-epic-achieved">Polymorphism epic achieved<a href="https://postgraphile.withfri.day/news/2025-06-07-last-epic-solved#polymorphism-epic-achieved" class="hash-link" aria-label="Direct link to Polymorphism epic achieved" title="Direct link to Polymorphism epic achieved" translate="no">​</a></h3>
<p>In previous versions of Gra<em>fast</em> there was the possibility of exponential plan
branching due to the naive method of resolution of abstract types.</p>
<p>By moving the responsibility of polymorphic resolution from field plan resolvers
into the abstract types themselves, we’ve centralized this logic, simplified
field plan resolvers, and unlocked more optimization opportunities and greater
execution efficiency. Polymorphic branches in one layer are now merged into a
single “combined” step before planning the next level of polymorphism.</p>
<figure><p><a href="https://postgraphile.withfri.day/assets/files/2025-06-06-combine-step-light-mode-2ae35af26be0f3b03158baf157d759ef.png" target="_blank"><img decoding="async" loading="lazy" alt="A plan diagram showing the old way polymorphism was handled. The nodes can branch exponentially." src="https://postgraphile.withfri.day/assets/images/2025-06-06-combine-step-light-mode-2ae35af26be0f3b03158baf157d759ef.png#light-mode-only" width="1560" height="1145" class="img_ev3q"></a>
<a href="https://postgraphile.withfri.day/assets/files/2025-06-06-combine-step-dark-mode-ef92ef013cd919cc1bb8bc3737d57eff.png" target="_blank"><img decoding="async" loading="lazy" alt="A plan diagram showing the new way, the branches are combined back together before moving to the next layer of resolution." src="https://postgraphile.withfri.day/assets/images/2025-06-06-combine-step-dark-mode-ef92ef013cd919cc1bb8bc3737d57eff.png#dark-mode-only" width="1560" height="1145" class="img_ev3q"></a></p><figcaption><p>On the right is the new handling of polymorphic resolution.<!-- --> <!-- -->
<code>getPetIds</code> and <code>getServiceAnimals</code> both fetch an<!-- --> <!-- -->
<code>Animal</code> ID and so they are combined together in order to fetch all
of the required Animals by their IDs. Once the IDs are fetched, the nodes can
branch out to the different Animal types.</p></figcaption></figure>
<p>Users of PostGraphile’s Postgres-based polymorphism should not need to take any action to
benefit from these changes, and may notice that their SQL queries are now
slightly smaller.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="typedefs--plans-overhaul">TypeDefs / plans overhaul<a href="https://postgraphile.withfri.day/news/2025-06-07-last-epic-solved#typedefs--plans-overhaul" class="hash-link" aria-label="Direct link to TypeDefs / plans overhaul" title="Direct link to TypeDefs / plans overhaul" translate="no">​</a></h3>
<p>In order to make the libraries more type safe, <code>makeGrafastSchema</code> (from
<code>grafast</code>) and <code>makeExtendSchemaPlugin</code> (from <code>postgraphile/utils</code>) have
deprecated the <code>typeDefs</code>/<code>plans</code> pattern since <code>plans</code> (like <code>resolvers</code> in the
traditional format) ended up being a mish-mash of lots of different types
(objects, scalars, enums, etc) and <code>__</code>-prefixed fields (<code>__resolveType</code>,
<code>__isTypeOf</code>, etc) for methods on the type itself.</p>
<p>Going forwards, the configuration should be split into <code>typeDefs</code> with
<code>objects</code>, <code>interfaces</code>, <code>unions</code>, <code>inputObjects</code>, <code>scalars</code> and <code>enums</code> as
appropriate. Type-level properties such as
<code>resolveType</code>/<code>isTypeOf</code>/<code>planType</code>/<code>scope</code>/etc are no longer prefixed with <code>__</code>
and, to avoid conflicts with these type-level properties, object and input
object fields should be specified inside a new <code>plans</code> property and enum values
within the new <code>values</code> property.</p>
<p><strong>The old pattern will still work</strong> (this is not a breaking change), but we
recommend moving to the new shape and will use it for all of our examples in the
documentation from now on.</p>
<p>Migration is quite straightforward:</p>
<ol>
<li class="">
<p><strong>Add new top-level properties</strong>. Add <code>objects</code>, <code>interfaces</code>, <code>unions</code>,
<code>inputObjects</code>, <code>scalars</code>, and <code>enums</code> as top level properties alongside
<code>typeDefs</code> and <code>plans</code>. Each should be an empty object. You can skip any
where you’re not defining types of that kind.</p>
</li>
<li class="">
<p><strong>Split definitions based on type kind</strong>. For each type defined in <code>plans</code>
move it into the appropriate new object (based on keyword defining the type;
i.e. <code>type</code> → <code>objects</code>, <code>interface</code> → <code>interfaces</code>, <code>union</code> →
<code>unions</code>, <code>input object</code> → <code>inputObjects</code>, <code>scalar</code> → <code>scalars</code>,
<code>enum</code> → <code>enums</code>).</p>
</li>
<li class="">
<p><strong>Move field plans into nested <code>plans: {...}</code> object</strong>. For each type defined
in the new <code>objects</code> and <code>inputObjects</code> objects: create a <code>plans: { ... }</code>
entry inside the type and move all fields (anything not prefixed with <code>__</code>)
inside this new (nested) property.</p>
</li>
<li class="">
<p><strong>Move enum values into nested <code>values: {...}</code> object</strong>. For each type
defined in the new <code>enums</code> object: create a <code>values: { ... }</code> entry inside
the type and move all values (anything not prefixed with <code>__</code>) inside this
new (nested) property.</p>
</li>
<li class="">
<p><strong>Remove <code>__</code> prefixes</strong>. For each type across
<code>objects</code>/<code>interfaces</code>/<code>unions</code>/<code>interfaceObjects</code>/<code>scalars</code> and <code>enums</code>:
remove the <code>__</code> prefix from any methods/properties.</p>
</li>
</ol>
<p>Example:</p>
<div class="language-diff codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-diff codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">typeDefs: ...,</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49">plans: {</span><br></div><div class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">objects: {</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">  User: {</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49">    __isTypeOf(v) {</span><br></div><div class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">    isTypeOf(v) {</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">      return v.username != null;</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">    },</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">   plans: {</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">      fieldName($source, fieldArgs) {</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">        // ...</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">      },</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">    },</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">  },</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">},</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">interfaces: {,</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">  MyInterface: {</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49">    __resolveType($specifier) {</span><br></div><div class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">    resolveType($specifier) {</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">      // ...</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">    }</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">  }</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">},</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">enums: {</span><br></div><div class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">  MyEnum: {</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">    ONE</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">    TWO</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">    THREE</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">  }</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">},</span><br></div></code></pre></div></div>
<p><em>(Aside: we pasted the
<a href="https://github.com/graphile/graphile.github.io/blob/6693b91d5dd9980b676876524d0a14d370800dcf/src/news/2025-06-06-last-epic-solved.md#L78-L150" target="_blank" rel="noopener noreferrer">markdown version<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>
of these instructions into ChatGPT and it managed to convert a number of plugins
perfectly! YMMV.)</em></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="and-more-besides">And more besides...<a href="https://postgraphile.withfri.day/news/2025-06-07-last-epic-solved#and-more-besides" class="hash-link" aria-label="Direct link to And more besides..." title="Direct link to And more besides..." translate="no">​</a></h3>
<p>In reaching this epic milestone, we have <strong>bumped the minimum version of Node.js to
Node 22</strong> (the latest LTS); we have also found and fixed a number of other issues both
in PostGraphile and the wider Graphile suite, you can see a full list at
<a href="https://www.graphile.org/news/20250607-last-epic-solved/" target="_blank" rel="noopener noreferrer">graphile.org<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-sponsors">Thank you sponsors<a href="https://postgraphile.withfri.day/news/2025-06-07-last-epic-solved#thank-you-sponsors" class="hash-link" aria-label="Direct link to Thank you sponsors" title="Direct link to Thank you sponsors" translate="no">​</a></h2>
<p>PostGraphile is crowd-funded open-source software, it relies on
crowd-sourced funding from individuals and companies to keep advancing.</p>
<p>If your company benefits from PostGraphile, Gra<em>fast</em> or the wider Graphile
suite, you should consider asking them to fund our work. By significantly
reducing the amount of work needed to achieve business goals and reducing
running costs, Graphile’s software results in huge time and money savings for
users. We encourage companies to contribute a portion of these savings back,
enabling the projects to advance more rapidly, and result in even greater
savings for your company.
<a href="https://graphile.org/sponsor/" target="_blank" rel="noopener noreferrer">Find out more about sponsorship on graphile.org<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>.</p>
<figure><p><img decoding="async" loading="lazy" alt="Thank you" src="https://postgraphile.withfri.day/assets/images/thank-you-c179c9ed75281d45ea6a8993ab3d0f59.svg" width="239" height="300" class="img_ev3q"></p></figure>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <author>
            <name>Jem</name>
            <uri>https://bsky.app/profile/jem.graphile.org</uri>
        </author>
        <category label="beta" term="beta"/>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[Major PostGraphile V5 beta release]]></title>
        <id>https://postgraphile.withfri.day/news/2025-03-24-beta-40-release</id>
        <link href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release"/>
        <updated>2025-03-24T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[A lot has been written behind the scenes to make PostGraphile V5 even better!]]></summary>
        <content type="html"><![CDATA[<div class="intro_ohxd"><p>In the first Gra<em>fast</em> Working Group, we outlined 4 <em>major</em> issues in Gra<em>fast</em>
that needed to be addressed before we could think about general release. With
this release, 3 of these are now complete!</p><ul>
<li class="">✅⤵️ Global dependencies - solved via "unary" steps</li>
<li class="">✅⤵️ Early exit - solved via "flags"</li>
<li class="">✅🎉 <strong>Eradicating eval - this release!</strong></li>
<li class="">🤔🔜 Polymorphism</li>
</ul><p>We’re proud to announce that the third of these, eradicating eval, is now
addressed with the launch of <code>grafast@0.1.1-beta.21</code>, and the approach has been
fully adopted and tested via incorporation into <code>postgraphile@5.0.0-beta.40</code>.</p></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-does-this-mean-for-postgraphile">What does this mean for PostGraphile?<a href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release#what-does-this-mean-for-postgraphile" class="hash-link" aria-label="Direct link to What does this mean for PostGraphile?" title="Direct link to What does this mean for PostGraphile?" translate="no">​</a></h2>
<p>Gra<em>fast</em> is a cutting-edge GraphQL planning and execution engine that leverages
the declarative nature of GraphQL to execute your requests with maximal
efficiency no matter the data sources you're working with. PostGraphile V5 uses
Gra<em>fast</em> as the underlying execution engine, allowing it to build much more
efficient SQL queries than PostGraphile V4 could achieve whilst also
significantly expanding the capabilities of the system - not to mention solving
some longstanding issues!</p>
<p>Whilst users of PostGraphile are not required to deeply understand the internals
of Gra<em>fast</em>, this focus of eradicating <code>$step.eval*()</code> methods from Gra<em>fast</em>
has given PostGraphile users some new benefits.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="sql-generation-moved-to-runtime">SQL generation moved to runtime<a href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release#sql-generation-moved-to-runtime" class="hash-link" aria-label="Direct link to SQL generation moved to runtime" title="Direct link to SQL generation moved to runtime" translate="no">​</a></h3>
<p>PostGraphile's various SQL-running steps like PgSelectStep now build their
queries at runtime rather than plan-time. They use the "builder" pattern, where
much of the SQL query can be established at plan-time, but final tweaks can be
applied at run-time (register tweaks via the <code>$pgSelect.apply($callback)</code>
method) before the query is built.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="sql-efficiency-increased">SQL efficiency increased<a href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release#sql-efficiency-increased" class="hash-link" aria-label="Direct link to SQL efficiency increased" title="Direct link to SQL efficiency increased" translate="no">​</a></h3>
<p>Since we have more information at run-time, our SQL queries were able to become
even simpler, 10% smaller on average across our test suite! This nets us a
modest performance improvement inside PostgreSQL, but the shift to runtime does
cost us a little performance in the JS layer since queries now need to be built
for every request, rather than once per plan. We're happy with this tradeoff;
one of the core goals of PostGraphile V5 (and the motivation for Gra<em>fast</em> in the
first place) was to shift load from the PostgreSQL layer (which is non-trivial
to scale) to the Node.js layer (which is easy to scale horizontally).</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="postgres-arrays-now-parse-5x-faster">Postgres Arrays now parse 5x faster<a href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release#postgres-arrays-now-parse-5x-faster" class="hash-link" aria-label="Direct link to Postgres Arrays now parse 5x faster" title="Direct link to Postgres Arrays now parse 5x faster" translate="no">​</a></h3>
<p>We've also <a href="https://github.com/bendrucker/postgres-array/pull/19" target="_blank" rel="noopener noreferrer">backported<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>
these <a href="https://github.com/bendrucker/postgres-array/pull/20" target="_blank" rel="noopener noreferrer">fixes<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> into the
<code>postgres-array</code> npm module for everyone that uses <code>pg</code> to benefit from.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="easier-to-write-sql-fragments">Easier to write SQL fragments<a href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release#easier-to-write-sql-fragments" class="hash-link" aria-label="Direct link to Easier to write SQL fragments" title="Direct link to Easier to write SQL fragments" translate="no">​</a></h3>
<p>Added a new feature to <code>pg-sql2</code> that allows us to handle non-SQL parameter
embeds with custom code, making it easier to write custom SQL, e.g. if a value
is already coming from SQL you can embed it directly without having to invoke
placeholder:</p>
<div class="language-diff codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-diff codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">const $fooId = $foo.get('id');</span><br></div><div class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49">$pgSelect.where(sql`foo_id = ${$pgSelect.placeholder($fooId)}`);</span><br></div><div class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa">$pgSelect.where(sql`foo_id = ${$fooId}`);</span><br></div></code></pre></div></div>
<p>We've also added the ability to embed dynamic SQL fragments that can be
dependent on runtime values (these values must be unary, i.e. they must come
from GraphQL field arguments or derivatives thereof):</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> $includeArchived </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> fieldArgs</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">getRaw</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"includeArchived"</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> $condition </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">lambda</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">$includeArchived</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">includeArchived</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">  includeArchived </span><span class="token operator" style="color:#393A34">?</span><span class="token plain"> sql</span><span class="token punctuation" style="color:#393A34">.</span><span class="token boolean" style="color:#36acaa">true</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> sql</span><span class="token template-string template-punctuation string" style="color:#e3116c">`</span><span class="token template-string sql language-sql">is_archived </span><span class="token template-string sql language-sql operator" style="color:#393A34">is</span><span class="token template-string sql language-sql"> </span><span class="token template-string sql language-sql boolean" style="color:#36acaa">false</span><span class="token template-string template-punctuation string" style="color:#e3116c">`</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#393A34"><span class="token plain">$pgSelect</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">where</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">$condition</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><br></div></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="join-our-testing-community">Join our testing community<a href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release#join-our-testing-community" class="hash-link" aria-label="Direct link to Join our testing community" title="Direct link to Join our testing community" translate="no">​</a></h3>
<p>If you use Discord, join our server at <a href="https://discord.gg/graphile" target="_blank" rel="noopener noreferrer">https://discord.gg/graphile<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> and chat away with other V5 users — talk over the new features, discuss any issues you encounter and explore different ways of using the new projects. We look forward to welcoming you and hearing of your suggestions and successes with V5!</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-sponsors">Thank you sponsors!<a href="https://postgraphile.withfri.day/news/2025-03-24-beta-40-release#thank-you-sponsors" class="hash-link" aria-label="Direct link to Thank you sponsors!" title="Direct link to Thank you sponsors!" translate="no">​</a></h2>
<p>PostGraphile is crowd-funded open-source software, it relies on
crowd-sourced funding from individuals and companies to keep advancing.</p>
<p>If your company benefits from PostGraphile or the wider Graphile
suite, you should consider asking them to fund our work. By significantly
reducing the amount of work needed to achieve business goals and reducing
running costs, Graphile’s software results in huge time and money savings for
users. We encourage companies to contribute a portion of these savings back,
enabling the projects to advance more rapidly, and result in even greater
savings for your company.
<a href="https://graphile.org/sponsor/" target="_blank" rel="noopener noreferrer">Find out more about sponsorship on graphile.org<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>.</p>
<figure><p><img decoding="async" loading="lazy" alt="Thank you" src="https://postgraphile.withfri.day/assets/images/thank-you-c179c9ed75281d45ea6a8993ab3d0f59.svg" width="239" height="300" class="img_ev3q"></p></figure>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <category label="beta" term="beta"/>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[PostGraphile V5 public beta — get involved!]]></title>
        <id>https://postgraphile.withfri.day/news/2023-08-03-version-5-beta</id>
        <link href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta"/>
        <updated>2023-08-03T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[It’s finally here! The day has come that you can get your hands on an early release of PostGraphile Version 5!]]></summary>
        <content type="html"><![CDATA[<div class="intro_ohxd"><p>It’s finally here! The day has come that you can get your hands on an <em>early release</em> of PostGraphile Version 5; but we do have an ask: please help us to get it ready for release.</p></div>
<p>We need help writing automated tests, validating it works in your real-world applications, improving the documentation, keeping up with issues and community support, porting plugins, smoothing edges, and as always we need financial support so we can keep investing our time into V5 and our other projects.</p>
<p>It has taken us 3.5 years to get to this point and we’re pretty happy with the result, but there’s still plenty to be done before we’re ready to give it the big V5.0.0 stamp of approval!</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-can-i-help">How can I help?<a href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta#how-can-i-help" class="hash-link" aria-label="Direct link to How can I help?" title="Direct link to How can I help?" translate="no">​</a></h2>
<p><strong>Help us to ensure that the documentation is ready.</strong> We’ve invested many weeks into writing the documentation for the various packages and projects (22 of them at last count!) which make up PostGraphile V5, but there’s still lots to do. We need people to read and follow the documentation, and to find the mistakes therein and submit issues or even patches.</p>
<p><strong>Help us to ensure that the software addresses your needs.</strong> We’ve spent three years building this system, but it’s only really been tested by other people in the last 6 months. Early signs are very positive, but we want to know: does it work for you? Does it do what you need it to?</p>
<p><strong>Help us to ensure that the transition from V4 is as easy as possible.</strong> We’ve spent a significant amount of time making the transition from V4 to V5 as easy as we can, building a preset that generates an almost identical schema, porting some of the V4 plugins to V5, and writing <a href="https://postgraphile.org/postgraphile/5/migrating-from-v4/" target="_blank" rel="noopener noreferrer">detailed migration documentation<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>. But we need your help: did migrating from V4 work well for you? Where were the rough edges, and how can we smooth them? Are you willing to help port community V4 plugin to V5?</p>
<p><strong>Help us to test V5.</strong> We have ported the V4 test suite over to V5 so we know that it works well for that, but there’s so many different combinations of options and plugins that you can do with PostGraphile that many have only been tested manually, and they really need automated tests to prevent regressions. We also need you to use V5 in your own applications and let us know how you get on — both negative and positive — to help us move towards the all-important 5.0.0 release.</p>
<p><strong>Help us to improve the experience of V5.</strong> We’ve put a lot of effort into both documentation and TypeScript types, but these can always be improved. There’s boilerplate in a few places that could be addressed with improvements to APIs, or with new abstractions. Try it out, and help us to improve the developer experience!</p>
<p><strong>Help us to educate people about V5.</strong> We don’t have a marketing department, we cannot afford a developer relations team or to sponsor big events. We’ll need your help to get the word out about PostGraphile V5, when the time comes; in the meantime we could really do with some help building example applications and tutorials to help people get started.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-does-beta-mean-for-postgraphile">What does “beta” mean for PostGraphile?<a href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta#what-does-beta-mean-for-postgraphile" class="hash-link" aria-label="Direct link to What does “beta” mean for PostGraphile?" title="Direct link to What does “beta” mean for PostGraphile?" translate="no">​</a></h2>
<p>We believe that <strong>PostGraphile V5 is suitable to run in production</strong> and that we’ve completed most of the significant API rewrites that we wanted to make. There’s still some expected (and maybe a couple unexpected) changes to come, but mostly the beta phase is there to gather feedback from the community about how it works for you, and to leave space to make breaking changes if they turn out to be necessary before we place the stamp on the final V5.0.0 release.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="tests-docs-and-examples">Tests, docs and examples<a href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta#tests-docs-and-examples" class="hash-link" aria-label="Direct link to Tests, docs and examples" title="Direct link to Tests, docs and examples" translate="no">​</a></h3>
<p>Many of the <a href="https://github.com/benjie/crystal/milestone/3" target="_blank" rel="noopener noreferrer">remaining issues<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> are to add tests, write documentation and build examples; if you’re someone who doesn’t like to ask politely for help and expects the documentation to be complete when they come to use the software then you should probably hold off from using PostGraphile V5 until the v5.0.0 release is out.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="typescript-types">TypeScript types<a href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta#typescript-types" class="hash-link" aria-label="Direct link to TypeScript types" title="Direct link to TypeScript types" translate="no">​</a></h3>
<p>One significant outstanding task which will likely cause some “breaking changes” is to review and potentially rewrite some of the TypeScript types. In some places types are a bit loose, in others there are old generics left around that are no longer needed, or generics in the wrong order, or other similar concerns. These issues don’t make the system unsafe to run in production, but they do require breaking changes to resolve, and we don’t want to have to jump to version 6 just to fix the TypeScript types of one of our APIs!</p>
<p>We would love your help with this if you’re good at TypeScript!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="other-nice-to-haves">Other “nice-to-haves”<a href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta#other-nice-to-haves" class="hash-link" aria-label="Direct link to Other “nice-to-haves”" title="Direct link to Other “nice-to-haves”" translate="no">​</a></h3>
<p>There are also a couple of other features that need to be added, for example integrating the Koa adaptor with Koa’s websocket framework like we've already done for Fastify. V4 of PostGraphile “emulated” an express stack for websocket connections in order to allow things like <code>pgSettings</code> to continue to function, but in V5 we’ll be better integrating the functionality of the different webservers — you’ll be able to read about that in Part 7 of <a href="https://dev.to/benjie/series/23459" target="_blank" rel="noopener noreferrer">our “Intro to V5” series<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>!</p>
<p>There’s also a bunch of optional enhancements that we’d really like to have in place before we launch v5.0.0 but if necessary we can do them later:</p>
<ul>
<li class="">digging into the generated SQL and optimizing it <em>even further</em>,</li>
<li class="">integrating the Node http2 webserver,</li>
<li class="">optimizing the code that’s exported by the Graphile Export command <a href="https://dev.to/graphile/intro-to-postgraphile-v5-part-6-excellent-executable-exports-1150" target="_blank" rel="noopener noreferrer">you may have read about last week<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>.</li>
</ul>
<p>There’s also the ongoing work to improve the tooling around our tooling, to make it easier for you to debug issues.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-do-i-try-it-out">How do I try it out?<a href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta#how-do-i-try-it-out" class="hash-link" aria-label="Direct link to How do I try it out?" title="Direct link to How do I try it out?" translate="no">​</a></h2>
<p>If you’re a V4 user then now is an excellent time to take V5 for a spin and let us know how you get on! You don’t even have to commit to migrating (though we hope once you’ve had a go you’ll definitely want to!), just some quick experiments with the things that you use PostGraphile for could be very useful.</p>
<p>You can read all about the new features in V5 in our new series <a href="https://dev.to/graphile/intro-to-postgraphile-v5-part-1-replacing-the-foundations-3lh0" target="_blank" rel="noopener noreferrer">Intro to V5<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> or if you prefer to just read the highlights, check out the migration guide’s <a href="https://postgraphile.org/postgraphile/5/migrating-from-v4/v5-new-feature-summary" target="_blank" rel="noopener noreferrer">new feature summary<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> and be sure to expand the bullets that have more details!</p>
<p>All the packages are published under the <code>@rc</code> tag, so you'll need to ensure you include that when issuing install instructions (e.g. <code>yarn add postgraphile@rc</code>).</p>
<p>The fastest way to try PostGraphile V5 is with our new <code>pgl</code> command which you don’t even have to install:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#393A34"><span class="token plain">npx pgl -P pgl/amber -e -c postgres:///my_db -s public</span><br></div></code></pre></div></div>
<p>(Replace the connection string and schema name with your database connection string and schema name(s).)</p>
<p>If you want to try PostGraphile V5 with a few plugins, one option is:</p>
<ol>
<li class="">Check out <a href="https://github.com/benjie/ouch-my-finger" target="_blank" rel="noopener noreferrer">https://github.com/benjie/ouch-my-finger<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li>
<li class="">Run <code>yarn</code> to install the dependencies</li>
<li class="">Run <code>yarn postgraphile -c postgres:///my_db -s public</code> giving your database’s connection string and schema(s)</li>
</ol>
<p>Ideally, you’d follow <a href="https://postgraphile.org/postgraphile/5/migrating-from-v4/" target="_blank" rel="noopener noreferrer">the migration guide<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> and start integrating V5 into your existing projects!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="join-our-testing-community">Join our testing community<a href="https://postgraphile.withfri.day/news/2023-08-03-version-5-beta#join-our-testing-community" class="hash-link" aria-label="Direct link to Join our testing community" title="Direct link to Join our testing community" translate="no">​</a></h3>
<p>If you use Discord, join our server at <a href="https://discord.gg/graphile" target="_blank" rel="noopener noreferrer">https://discord.gg/graphile<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> and chat away with other V5 users — talk over the new features, discuss any issues you encounter and explore different ways of using the new projects. We look forward to welcoming you and hearing of your suggestions and successes with V5!</p>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <author>
            <name>Jem</name>
            <uri>https://bsky.app/profile/jem.graphile.org</uri>
        </author>
        <category label="beta" term="beta"/>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
    <entry>
        <title type="html"><![CDATA[PostGraphile V5 alpha is here!]]></title>
        <id>https://postgraphile.withfri.day/news/2023-04-26-version-5-alpha</id>
        <link href="https://postgraphile.withfri.day/news/2023-04-26-version-5-alpha"/>
        <updated>2023-04-26T00:00:00.000Z</updated>
        <summary type="html"><![CDATA[PostGraphile Version 5 is now ready to run in some production environments!]]></summary>
        <content type="html"><![CDATA[<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="now-production-ready-for-some-environments">Now production ready… for some environments<a href="https://postgraphile.withfri.day/news/2023-04-26-version-5-alpha#now-production-ready-for-some-environments" class="hash-link" aria-label="Direct link to Now production ready… for some environments" title="Direct link to Now production ready… for some environments" translate="no">​</a></h3>
<p>January marked a big milestone for PostGraphile Version 5, when it began the prealpha stage - where early adopters could install the packages from npm (if they knew the secret 😉) and easily test V5 within their current stacks. Up until that point, it was only possible to run the project by cloning the repository and building it yourself - not ideal for serious testing!</p>
<p>Throughout the prealpha phase we smoothed the edges, closed gaps, tidied APIs, discovered which pieces of terminology worked and which did not, and did a lot of API restructuring and stabilization.</p>
<p>With thanks to everyone in the V5 testing community - and a special shout out for the excellent and continued feedback from our sponsors dfg, hov, James, Josiah and the Netflix team, mattste, Simon, and Timo - we are in a much better shape three months on. We now have a <a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4">detailed migration guide</a>, <a href="https://postgraphile.withfri.day/postgraphile/5">updated docs</a>, an enhanced developer experience and much improved backwards compatibility!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="whats-new-in-version-5">What’s new in Version 5?<a href="https://postgraphile.withfri.day/news/2023-04-26-version-5-alpha#whats-new-in-version-5" class="hash-link" aria-label="Direct link to What’s new in Version 5?" title="Direct link to What’s new in Version 5?" translate="no">​</a></h3>
<p>Our main aim in V5 was to replace the cumbersome lookahead system with something much more pleasant and powerful. To serve this need we iterated and iterated, and ultimately invented Gra<em>fast</em>: a new planning and execution engine for GraphQL (see our public video introduction <a href="https://youtu.be/H26uBe_lLag" target="_blank" rel="noopener noreferrer">on YouTube<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>). Gra<em>fast</em> uses a declarative planning system which brings with it a new, holistic approach to executing GraphQL queries. For you, this means simpler abstractions, better performance, and code which is easier to read and maintain.</p>
<p>Gra<em>fast</em> even generates a plan diagram showing what steps are necessary to execute your operation and how the data flows between each of the steps, which is a massive boon to debugging both for you, and for us!</p>
<figure><p><a href="https://postgraphile.withfri.day/assets/files/2023-04-26-mermaid-diagram-24e7d632d46178a99b3c8063d64f5e54.png" target="_blank"><img decoding="async" loading="lazy" alt="A Grafast plan diagram for an AllPosts query" src="https://postgraphile.withfri.day/assets/images/2023-04-26-mermaid-diagram-24e7d632d46178a99b3c8063d64f5e54.png" width="2024" height="1832" class="img_ev3q"></a></p><figcaption><p>An autogenerated Gra<em>fast</em> plan diagram for the displayed GraphQL query. Plan diagrams detail the steps required to complete a GraphQL request and show how the data flows between them. See <a href="https://grafast.org/grafast/plan-diagrams" target="_blank" rel="noopener noreferrer">"Plan Diagrams"<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> in the Gra<em>fast</em> documentation for more details.</p></figcaption></figure>
<p>Thanks to these advanced planning capabilities, PostGraphile is now able to generate much more optimal (and easier to read!) SQL queries and offload significant work from the database, allowing your applications to scale even further than previously possible.</p>
<figure><p><a href="https://postgraphile.withfri.day/assets/files/2023-04-26-v4-v5-comparison-1315f1de634b5e9dbd3debab6af81748.png" target="_blank"><img decoding="async" loading="lazy" alt="A GraphQL query for AllPosts" src="https://postgraphile.withfri.day/assets/images/2023-04-26-v4-v5-comparison-1315f1de634b5e9dbd3debab6af81748.png" width="3200" height="1800" class="img_ev3q"></a></p><figcaption><p>An example of the vast improvement in the autogenerated SQL queries in Version 5 as compared to Version 4 for the same <a href="https://postgraphile.withfri.day/assets/files/2023-04-26-comparison-query-ruru-a918f9cbde5c2442dd6b8bd0284692ae.png" target="_blank">GraphQL “AllPosts” query</a>. Generated SQL is now easier to understand and debug, and the V5 SQL query shown is twice as fast as the V4 SQL query.</p></figcaption></figure>
<p>Since the lookahead system underpinned everything in Version 4, replacing it meant we needed to rebuild everything from the ground-up on these new, more solid and capable foundations. We decided to use this opportunity to fix a huge number of other niggles and suboptimal experiences that were present in V4 - and also enable a decent complement of capabilities that simply were not possible in the V4 architecture. Ultimately, Version 5 brings a number of new paradigms to PostGraphile; some of the main features of PostGraphile V5 you'll be able to enjoy include:</p>
<ul>
<li class="">Multiple forms of database-based polymorphism (producing GraphQL interfaces and unions)</li>
<li class="">GraphQL’s new incremental delivery (<code>@stream</code> and <code>@defer</code> directives) [early version]</li>
<li class="">Exporting your executable schema as optimized JS code</li>
<li class="">New “behavior” system that fixes the shortcomings of <code>@omit</code> and similar smart tags</li>
<li class="">Massively enhanced TypeScript typings throughout</li>
<li class="">Generate personalized documentation based on the plugins and presets you’re using</li>
<li class="">On-demand transactions - enabling workflows which Version 4’s model precluded</li>
<li class="">Consolidated configuration across CLI, library and schema-only usage</li>
<li class="">Shareable and composable presets</li>
<li class="">A unified and more powerful plugin system</li>
<li class="">And much, much more!</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="its-in-alpha-jim-but-not-as-we-know-it">It’s in Alpha, Jim, but not as we know it<a href="https://postgraphile.withfri.day/news/2023-04-26-version-5-alpha#its-in-alpha-jim-but-not-as-we-know-it" class="hash-link" aria-label="Direct link to It’s in Alpha, Jim, but not as we know it" title="Direct link to It’s in Alpha, Jim, but not as we know it" translate="no">​</a></h3>
<p>While some projects use the alpha phase for discovery and prototyping, and suffer through countless breaking changes and critical bugs, we've already completed that phase – we’re ready to take things to the next level.</p>
<p>Now is the time for you to try out V5! We're confident that our software will generate a fully functional GraphQL schema for you, and it already passes the full suite of Version 4 tests (plus many more), and is in use by a number of testers. We even made a V4 preset and detailed migration guide to allow you to get started as easily as possible.</p>
<p><strong>If you don’t try V5 until after its public release then it may be too late to comment on things that could have been improved</strong>. Though we believe our APIs are already in near-final form, remaining in alpha phase gives us the freedom to apply breaking changes to APIs if the benefits outweigh the costs.</p>
<p>Get involved! Does it solve your problems? Can we make it easier for you to migrate to? Are there performance regressions? Do the TypeScript types align with your usage?</p>
<p><a href="https://postgraphile.withfri.day/postgraphile/5/migrating-from-v4">Visit the migration guide to get started</a>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-to-use-version-5-today">Where to use Version 5 today<a href="https://postgraphile.withfri.day/news/2023-04-26-version-5-alpha#where-to-use-version-5-today" class="hash-link" aria-label="Direct link to Where to use Version 5 today" title="Direct link to Where to use Version 5 today" translate="no">​</a></h3>
<p>If you’re using PostGraphile with purely pre-vetted operations (e.g. via persisted operations), or are using PostGraphile with an API audience which is generally trusted (e.g. as internal services within your company) then with careful consideration and monitoring you should be safe to put V5 into production today. Early results from testers have been very promising!</p>
<p>If you’re using PostGraphile in a more public facing capacity and are not protecting it with an operation allowlist then you may want to start testing on your development and staging servers but hold off from a production release until we’ve added a few additional safety measures (for example, adding a planning timeout to prevent denial of service through expensive planning attacks).</p>
<p>If you just want to help out in the testing of V5 without shipping to production, you should check out our quick start repo, <a href="https://github.com/benjie/ouch-my-finger" target="_blank" rel="noopener noreferrer">ouch-my-finger<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>, which is kept up to date with the latest V5 releases. It’s a great way to connect to your database in a test environment and give V5 a go, and also a great way to send reproducible test cases to us if you hit any snags.</p>
<p>As the alpha progresses we hope, with the help of your feedback and testing, the software will become more and more suitable for running in various production environments. We can't wait to see what you build with it!</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="beyond-alpha">Beyond Alpha...<a href="https://postgraphile.withfri.day/news/2023-04-26-version-5-alpha#beyond-alpha" class="hash-link" aria-label="Direct link to Beyond Alpha..." title="Direct link to Beyond Alpha..." translate="no">​</a></h3>
<p>By the end of the alpha phase, we should all be confident that V5 is safe to run in production, and all the expected API changes should be complete. Then we'll move onto the beta phase, during which we'll focus on performance, documentation, and also improving the experience. For example, this would be the phase during which we'll be putting time into making sure that the schema exporting functionality is outputting pleasant code, and making it easy for plugin developers to indicate whether or not their plugins support exporting.</p>
<p>Work helping to migrate V4 community plugins to V5 will also continue during this phase, as may experimentation with additional functionality such as live queries. Beta users should find the API stability much improved since the alpha, but we still reserve the right to release breaking API changes if they have substantial benefits.</p>
<p>By the end of the beta phase, the APIs should be stable, the software should be performant, and everyone involved should be confident running it in production. Then we'll take the final beta and release it as "release candidate 1," and all going well, ultimately release that as PostGraphile v5.0.0.</p>
<p>It has been a long road to get here, and we thank you all so much for your continued support - we could never have accomplished this feat without you! We really hope you're going to love PostGraphile V5 and all the new technology and tooling that it introduces to make your jobs both easier and more fun. Thank you!</p>
<p><em>Keep your eyes peeled for a series of articles going into a greater depth about each of the new features of Version 5, a digest of which will be shared to our mailing list, our <a href="https://discord.gg/graphile" target="_blank" rel="noopener noreferrer">community Discord<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a> and <a href="https://fosstodon.org/@graphile" target="_blank" rel="noopener noreferrer">social media<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a>.</em></p>]]></content>
        <author>
            <name>Benjie</name>
            <uri>https://github.com/Benjie</uri>
        </author>
        <author>
            <name>Jem</name>
            <uri>https://bsky.app/profile/jem.graphile.org</uri>
        </author>
        <category label="alpha" term="alpha"/>
        <category label="releases" term="releases"/>
        <category label="v5" term="v5"/>
    </entry>
</feed>