Graphile News

PostGraphile and Grafast release candidate!

Tue, 28 Oct 2025 12:00:00 GMT

Announced 2025-10-28 by the Graphile Team

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

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

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

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

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

Why this is still a release candidate

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

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

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

Thinking in plans

For those using Grafast outside of PostGraphile, now is the perfect moment to validate that the “plans as dataflow” approach clicks for you: do you understand the separation of “plan-time” and “execution-time”? Can you see how principled communication between the steps allows for optimization without needing to revisit plan resolvers?

If you don’t understand it, that’s likely a failing of our documentation! Help us improve our explanations by sharing your feedback (whether confusion and frustration or success and praise!) in our Discord or with GitHub issues and pull requests!

Visit the announcement on PostGraphile.org for specific news about PostGraphile V5 and how to get the release candidate up and running.

Visit the announcement on Grafast.org for news about Grafast V1 - the new GraphQL planning and execution engine which powers PostGraphile under-the-hood.

Thank you Sponsors

Grafast and PostGraphile are crowd-funded open-source software, they rely on crowd-sourced funding from individuals and companies to keep advancing.

If your company benefits from Grafast, 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. Find out more about sponsorship here on our website.

Grafast beta: last epic solved!

Sat, 07 Jun 2025 12:00:00 GMT

Announced 2025-06-07 by the Graphile Team

In the first Grafast Working Group, we outlined 4 major issues in Grafast that needed to be addressed before we could think about general release. The fourth, and final, epic has now been solved!

✅ Global dependencies — solved via “unary” steps
✅ Early exit — solved via “flags”
✅ Eradicating eval
✅ Polymorphism — this release!

In previous versions of Grafast there was the possibility of exponential plan branching due to the naive method of resolution of abstract types — a known issue raised in the first Grafast working group as one of four “epics” to be solved before v1.0. This release of grafast@0.1.1-beta.22 (used as the core execution engine in postgraphile@5.0.0-beta.41) fixes this final epic through a complete overhaul of the polymorphism system. Let’s take a look!

Polymorphism epic achieved

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. We no longer have the concept of “polymorphic capable” steps: any step may now be used for polymorphism. Abstract types now gain a planType method responsible for taking a “specifier” from the field plan resolver and returning a step representing the name of its concrete object type along with subplans for each possible object types.

To solve the problem of exponential branching, we merge the new “specifier” steps from all of the previous polymorphic branches into a single combined step before planning the next level of polymorphism.

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.

For the few of you who have been brave enough to hand write polymorphic plan resolvers: first of all, thank you for trying it out! Hand written polymorphic plan resolvers will need to be updated to match the new paradigm, this will involve moving the polymorphic resolution from field plan resolvers into the new planType method on the relevant abstract type (interface or union) and adjusting the logic to fit the new pattern. Steps such as polymorphicBranch, pgPolymorphism, and other polymorphism related steps no longer exist as they are no longer supported or needed in this new paradigm. For guidance on how to write the planType method, see the Grafast docs and please reach out to us on Discord or GitHub issues — we’d love to help you get migrated.

Excitingly this is the last change to hand written plan resolvers that we expect to make for v1.0 (other than some improvements around TypeScript types), so we're getting a lot closer to release candidate stage!

TypeDefs / plans overhaul

In order to make the libraries more type safe, makeGrafastSchema (from grafast) and makeExtendSchemaPlugin (from postgraphile/utils) have deprecated the typeDefs/plans pattern since plans (like resolvers in the traditional format) ended up being a mish-mash of lots of different types (objects, scalars, enums, etc) and __-prefixed fields (__resolveType, __isTypeOf, etc) for methods on the type itself.

Going forwards, the configuration should be split into typeDefs with objects, interfaces, unions, inputObjects, scalars and enums as appropriate. Type-level properties such as resolveType/isTypeOf/planType/scope/etc are no longer prefixed with __ and, to avoid conflicts with these type-level properties, object and input object fields should be specified inside a new plans property and enum values within the new values property.

The old pattern will still work (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.

Migration is quite straightforward:

Add new top-level properties. Add objects, interfaces, unions, inputObjects, scalars, and enums as top level properties alongside typeDefs and plans. Each should be an empty object. You can skip any where you’re not defining types of that kind.
Split definitions based on type kind. For each type defined in plans move it into the appropriate new object (based on keyword defining the type; i.e. type → objects, interface → interfaces, union → unions, input object → inputObjects, scalar → scalars, enum → enums).
Move field plans into nested plans: {...} object. For each type defined in the new objects and inputObjects objects: create a plans: { ... } entry inside the type and move all fields (anything not prefixed with __) inside this new (nested) property.
Move enum values into nested values: {...} object. For each type defined in the new enums object: create a values: { ... } entry inside the type and move all values (anything not prefixed with __) inside this new (nested) property.
Remove __ prefixes. For each type across objects/interfaces/unions/interfaceObjects/scalars and enums: remove the __ prefix from any methods/properties.

Example:

 typeDefs: ...,
-plans: {
+objects: {
   User: {
-    __isTypeOf(v) {
+    isTypeOf(v) {
       return v.username != null;
     },
    plans: {
       fieldName($source, fieldArgs) {
         // ...
       },
+    },
   },
+},
+interfaces: {,
   MyInterface: {
-    __resolveType($specifier) {
+    resolveType($specifier) {
       // ...
     }
   }
+},
+enums: {
   MyEnum: {
     ONE
     TWO
     THREE
   }
 },

(Aside: I pasted the markdown version of these instructions into ChatGPT and it managed to convert a number of plugins perfectly! YMMV.)

Other changes:

ObjectPlans/GrafastPlans/FieldPlans/InputObjectPlans/ScalarPlans all changed to singular
InterfaceOrUnionPlans split to InterfacePlan/UnionPlan (identical currently)
Shape of ObjectPlan/InterfacePlan/UnionPlan has changed; DeprecatedObjectPlan/etc exist for back-compatibility
FieldArgs can now accept an input shape indicating the args and their types
FieldPlanResolver<TArgs, TParentStep, TResultStep> has switched the order of the first two generic parameters: FieldPlanResolver<TParentStep, TArgs, TResultStep> — this is to reflect the order of the arguments to the function. Also null has been removed from the generics.
Various generics (including GrafastFieldConfig) that used to take a GraphQL type instance as a generic parameter no longer do — you need to use external code generation because TypeScript cannot handle the dynamic creation.
GrafastFieldConfig last two generics swapped order.
GrafastArgumentConfig generics completely changed

Grafast features

New steps

coalesce(): Accepts a number of steps and represents the first value from them that isn’t null or undefined

Step classes

Experimental support for adding “references” to other steps at plan-time only (via refId = this.addRef($step) and reciprocal $step = this.getRef(refId) methods). Useful for optimization; but use with great caution. Currently undocumented due to experimental nature.

Grafserv

Add @whatwg-node/server HTTP adaptor, thanks to @kzlar 🎉

Improved type-safety

each() now reflects the type of the list item even if it’s not a “list capable” step
loadOne()/loadMany() can now track the underlying nullability of the callback

🚨 This will potentially break your plan types quite a bit. In particular, the LoadOneCallback and LoadManyCallback types now have 5 (not 4) generic parameters, the new one is inserted in the middle (after the second parameter) and indicates the true return type of the callback (ignoring promises) — e.g. Maybe<ReadonlyArray<Maybe<ItemType>>> for LoadManyCallback. They have sensible defaults if you only specify the first two generics.

Other breaking changes

Minimum version of Node.js bumped to Node 22 (the latest LTS) in preparation for release candidate
Grafserv: Naked GraphQL errors (such as those you’d see from coercion) are now treated as safe to output.
graphile-export now supports and possibly requires ESLint v9.
Grafast: plan JSON now has layer plans as a list rather than a tree, to account for combination layer plans that have many parents. May not be compatible with previous versions of Ruru.

Bug fixes

Grafast: Fix bug in deduplication that only compared flags on first dependency.
Grafast: Fix a number of edge-case issues relating to incremental delivery
PostGraphile: Fix bug in nullable nodeID handling for computed column arguments with the Relay preset that was causing the entire PgSelectStep to be inhibited on null/undefined.
PostGraphile: Fix bug with @ref ... plural smart tag where multiple @refVia are present but the target type is not abstract.

And here’s the rest...

Grafast: Implement deduplication of loadOne() / loadMany() and jsonParse() steps
Grafast: Planning field inputs now uses a cache so planning time should reduce marginally and step ids will be less inflated.
Grafast: Don’t call applyPlan on arguments if the value is not specified (not even a variable) and there’s no default value.
Grafast: Fixes bug where undefined values might not be flagged with FLAG_NULL
PostGraphile: General plan efficiency improvements
Ruru: Upgrade to Mermaid 11, and reduce verbosity of polymorphism in plan diagrams.
Ruru: Removes a lot of cruft from plan diagrams by hiding certain over-used global dependencies.
Grafserv: Add ctx.ws?.normalizedConnectionParams which can be treated as headers (i.e. has lower-cased keys).
@dataplan/pg: pgSelectFromRecord no longer requires a mutable array
Graphile Export: graphile-export now uses ES2022 syntax for ESLint check on exported schema, fixing compatibility with @graphile/pg-aggregates.
Graphile Export: Fix detection of SQL when pg-sql2 isn’t available at runtime, and improve misleading error around class instances
pg-sql2: util.inspect(someSql) will now output a much nicer string

Thank you Sponsors

Grafast and PostGraphile are crowd-funded open-source software, they rely on crowd-sourced funding from individuals and companies to keep advancing.

Major Grafast beta: three down, one to go

Mon, 24 Mar 2025 17:00:00 GMT

Announced 2025-03-24 by Benjie

In the first Grafast Working Group, we outlined 4 major issues in Grafast that needed to be addressed before we could think about general release. With this release, 3 of these are now complete!

✅⤵️ Global dependencies - solved via "unary" steps
✅⤵️ Early exit - solved via "flags"
✅🎉 Eradicating eval - this release!
🤔🔜 Polymorphism

After 3 months of gruelling work, we're proud to announce that the third of these, eradicating eval, is now addressed with the launch of grafast@0.1.1-beta.21 (used as the core execution engine in postgraphile@5.0.0-beta.39). Let's look into what that has meant.

Input evaluation moved to runtime

Since the beginning, Grafast has had the ability to add plan resolvers not just to fields, not just to arguments, but also to input object fields (including those within lists). This made Grafast's planning really ergonomic for things like nested filters, which was great for PostGraphile! But it turns out it's really problematic for certain shapes of input — planning would put constraints on the variables compatible with the plan, requiring potentially unlimited numbers of operation plans needing to be built for the same GraphQL document. Worse: for large input trees involving lists, the number of steps generated could be overwhelming, resulting in the deduplication phase taking excessive time.

One particular user example that could cause 4 minutes of planning time from just a 100kB input made it clear that we had overreached with using plan resolvers too deep into inputs; so we've scaled it back so that you can only add plan resolvers to fields and arguments, you can no longer attach applyPlan or inputPlan to input object fields. This was something that we used a lot internally (hence the huge time investment migrating away!), but very few people (no-one?) used externally so it was ripe for removal.

That problematic query that took 4 minutes to plan before? It now takes 1.1ms to plan, yielding a 200,000x speedup!

What does this mean for my codebase?

Hopefully good things! Please update to the latest @beta of all the PostGraphile and/or Grafast related modules you're using (including plugins) and for most users everything should work as before, only better.

I've outlined some of the most common changes you may need to make below, but if you are impacted by any other changes, please ask for help in the chat — AFAIK most of the other things that have had significant changes are used by almost no-one except me, so it doesn't make sense for me to invest time documenting it here. If you're curious, many items are documented in both the changelogs and the pull requests where the changes occurred.

Change `fieldArgs.get` to `fieldArgs.getRaw`

Because we've removed inputPlan, the fieldArgs.get(key) method is no more; instead use fieldArgs.getRaw(key) which is equivalent unless the inputs had plans (which they cannot any more).

Converting `applyPlan` and `inputPlan`

If your input object fields did have plan resolvers then instead of having Grafast automatically call them on each and every input field recursively at plan-time, we now have the applyInput and bakedInput steps that represent runtime application or transform of these inputs recursively via a single step in our plan diagram.

We've managed to make this new runtime system very similar in shape to the old plan-time system, so PostGraphile plugins don't need to change much — this was largely enabled by how closely we managed to get the Grafast plan syntax to the syntax of code you would normally write at runtime. The first change is to rename applyPlan to apply, and inputPlan to baked. From there, your code might just work straight away, or it might need some more small tweaks (e.g. fieldArgs is no longer present, it's been replaced with simply the runtime value of the current field).

No more `$step.eval*()`

The eval methods are now marked as internal so you will get TypeScript errors if you try and use them. They will likely be removed at some point after release, so you should be sure to migrate away from using them at your earliest opportunity. But you weren't using them anyway… right?

ExecutableStep renamed to Step

This one is more cosmetic…

Since we no longer have plan resolvers deep in inputs, we no longer have the ModifierStep system that was used for managing them (it's been replaced with Modifier which happens at runtime). Since we no longer have ModifierStep, we no longer need BaseStep to be separate from and inherited by ExecutableStep, so we've merged them. Since this is the base class for all steps now, we've renamed it to simply Step.

We have kept an ExecutableStep export for backwards compatibility.

PostGraphile changes

In addition to the changes above that impact everything that uses Grafast, here are some of the changes that specifically impact PostGraphile users.

SQL generation moved to runtime

PostGraphile's various SQL-running steps like PgSelectStep now build their queries at runtime rather than plantime. 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 $pgSelect.apply($callback) method) before the query is built.

SQL efficiency increased

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 Grafast 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).

Postgres Arrays now parse 5x faster

I've also backported these fixes into the postgres-array npm module for everyone that uses pg to benefit from.

Easier to write SQL fragments

Added a new feature to pg-sql2 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:

 const $fooId = $foo.get('id');
-$pgSelect.where(sql`foo_id = ${$pgSelect.placeholder($fooId)}`);
+$pgSelect.where(sql`foo_id = ${$fooId}`);

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):

const $includeArchived = fieldArgs.getRaw("includeArchived");
const $condition = lambda($includeArchived, includeArchived =>
  includeArchived ? sql.true : sql`is_archived is false`
);
$pgSelect.where($condition);

Additional changes

makeGrafastSchema

🚨The structure of makeGrafastSchema as it relates to arguments and input object fields has changed a little; use TypeScript to guide you. I'm hoping this is the last change of its kind before release.
New shortcuts added for argument applyPlan() and input field apply() methods.
Trimmed a load of unnecessary exported code, such as empty objects and field resolvers that do the same as the default field resolver.
Fix bug in makeGrafastSchema that fails to build schema sometimes if a field uses a function shortcut rather than object definition.
Fix bug in makeGrafastSchema that sometimes doesn't allow defining input objects

🚨 If you use graphile-export to export your schema as executable code, be sure to regenerate your schemas as the old generated code could be misinterpreted by the new makeGrafastSchema.

graphile-export

Massively improved the executable code output from graphile-export in combination with the changes to makeGrafastSchema above.
PostGraphile's "kitchen sink" schema export code now outputs 37KLOC rather than 47KLOC - a significant reduction in complexity!

Improved plan diagrams

Plan diagrams now reveal (via @s text) if a step is meant to be streamed.
Constant steps improved.
Object: null prototype simplified to § in output.
Hoist steps during optimize phase.
We no longer render dependencies on the undefined constant, because it's messy and doesn't add value
We group when there are multiple dependencies to the same step from the same step, and label the line with the count instead.

Step classes

When writing your own step classes:

ExecutionValue has gained a new .unaryValue() method that returns the unary value for unary execution values, and throws an error for non-unary execution values. This is much safer than the previous .at(0) trick which did not assert that you were actually dealing with a unary execution value.
If you were using @stream (incremental delivery) and had written your own Step class with stream support, first of all: amazing! Please let me know you did that (via email or Discord)! Secondly, you'll need to either rename your stream function to execute or merge its code into your existing execute method if you have one. It turns out there wasn't much point in separating them, and you can confer a lot of benefit from merging them.

Other Grafast improvements

Compatible mutation operations can now complete synchronously via grafastSync()
Fixes bug in input objects where keys that weren't set would still be present with value undefined
Fix bug in step caching relating to polymorphism
New items() conventional method for extracting the items from a collection (makes for easier compatibility with connections)
Error handling improved
Lists improved - especially error handling and deduplication logic; as well as allowing returning connection-capable steps in list positions
Optimization to Grafast's internal execution values, which are used heavily in hot paths.

Thank you Sponsors

Grafast and PostGraphile are crowd-funded open-source software, they rely on crowd-sourced funding from individuals and companies to keep advancing.

If your company benefits from Grafast, 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. Find out more about sponsorship here on our website.

PostGraphile V5 public beta — get involved!

Thu, 03 Aug 2023 01:00:00 GMT

Announced 2023-08-03 by the Graphile Team

It’s finally here! The day has come that you can get your hands on an early release of PostGraphile Version 5; but we do have an ask: please help us to get it ready for release.

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. Find out what this means for you at the new PostGraphile website.

Intro to V5

We have continued to detail the new exciting features in PostGraphile Version 5. Particularly exciting are those in Parts 5 & 6 - a pair of brand new features which can unlock new possibilities for your projects. Find the full “Intro to V5” series on dev.to, covering the following:

Replacing the Foundations
Plug-ins and Presets
Introspection and Abstraction
Making the Schema Yours
Polymorphism!
Excellent Executable Exports

If you appreciate the work we do, and you want to help us to continue doing it, then please support development of this project via sponsorship. With your support we can improve performance, usability and documentation at a greater rate, leading to reduced running and engineering costs for your organisation, leading to a net ROI. Find out how to sponsor here.

Intro to PostGraphile V5 — a new blog series!

Thu, 22 Jun 2023 01:00:00 GMT

Announced 2023-06-22 by the Graphile Team

In our new blog post series, we are beginning to lift the curtain of secrecy which has surrounded Version 5 for the past few years. Each week, Benjie will dive in to a key feature of this massive new release.

This week we are starting with an exploration of replacing the look-ahead system. In the post, you'll find out why we invented Grafast (our new planning and execution engine for GraphQL); see examples of the straightforward “plan resolvers” that PostGraphile V5 uses; and revel in the significantly simplified and more efficient SQL queries that V5 generates.

See the blog series on dev.to

PostGraphile V5 Sponsors Early Access

April marked a big milestone for PostGraphile Version 5, when it entered the alpha stage.

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're now confident V5 is suitable to run in production. Work preparing for final release is still ongoing, but we now have a detailed migration guide, updated docs, an enhanced developer experience and much improved backwards compatibility!

With the beta just around the corner, now is the perfect time to join our sponsors and test Version 5. 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. All sponsors are invited to join the early access program, if you already sponsor us please get in contact and we'll arrange an access code for you and your team.

Thank you for sponsoring the project!

Our ability to innovate and make our tooling freely available would not be possible without our sponsors, thank you to each and every sponsor - past and present - for the financial support to keep building tools which serve you. For everyone else, find out how to sponsor here.

Step Aside Resolvers: a New Approach to GraphQL Execution

Thu, 08 Dec 2022 01:00:00 GMT

2022-12-07

This week at GraphQL Galaxy, Benjie introduced his vision for a new general-purpose GraphQL execution strategy whose holistic approach could lead to significant efficiency and scalability gains for all GraphQL APIs. This talk is the first public look at the ludicrously speedy, general purpose and holistic advanced planning and execution engine codenamed Grafast.

Grafast is already available to Graphile sponsors whilst it is still undergoing heavy iteration. All sponsors can request access to the binaries and documentation; Featured Tier sponsors can gain access to the repository, issues and support. Find out more about sponsorship on our website.

You can also see the talk on YouTube.

Development Support Now Available

Thu, 20 Oct 2022 01:00:00 GMT

2022-10-20

The Graphile team are pleased to introduce a new Development Support offering, drawing on their experience as educators and leaders in the GraphQL ecosystem. Development Support gives your organization access to the knowledge and experience of the Graphile team for any issues you have with PostGraphile, the Graphile suite and other tools in the ecosystem such as TypeScript, SQL, Node.js, GraphQL and more.

Graphile maintainer, GraphQL TSC member and keynote speaker Benjie is well placed to offer Development Support for PostGraphile and related technologies in the GraphQL ecosystem. Together with the Graphile team, he will lend his expertise to your in-house development and push for faster, safer and more robust software development and practices.

Find out more about the Graphile support offering here.

Graphile Worker 0.14 - Batch Jobs

Tue, 11 Oct 2022 01:00:00 GMT

Announced 2022-10-11 by the Graphile Team

Graphile are pleased to announce the release of Graphile Worker 0.14, which includes many new significant changes in preparation for moving towards version 1.0.

Batch Jobs

Normally a job's payload is an object; however jobs are also allowed to have a payload which is an array of objects. Jobs of this type are called "batch jobs" and they have a few special behaviours:

when you use job_key in replace or preserve_run_at mode, when a job is replaced/updated, instead of overwriting the payload, the existing and new payloads will be merged into a larger array (this only occurs when the existing and new payloads are both arrays, otherwise the payload is simply replaced).
when a task executes a batch job, it may return a list of promises that is the same length as the payload array. If any of these promises reject, then the job is said to have 'partial success', the result of which is it being sent back to the queue for a retry, but with the successful objects removed from the payload so only the failed objects will be retried.

Batch jobs can be useful where you need to aggregate multiple tasks together over time for efficiency; for example if you have a notification system you might schedule a notification to be sent to a user in 2 minutes time that they received a DM. Over the next 2 minutes if any other DMs are received, these can be appended to the job payload such that when the job executes it can inform the user of all of these DMs, not just the latest one.

Other Features

Significantly improved 'large jobs table' performance (e.g. when a large queue is locked, or there's a lot of jobs queued for task identifiers your worker instance doesn't support, or a lot of failed jobs). There's around 20x improvement in this 'worst case' performance for real user workloads.
Added new (experimental) much faster add_jobs batch API.
Fix error handling of cron issues in 'run' method.
CronItem.match can now accept either a pattern string or a matcher function.

See the full update in the project's release notes.

Please support development of this project via sponsorship. With your support we can improve performance, usability and documentation at a greater rate, leading to reduced running and engineering costs for your organisation, leading to a net ROI. Find out how to sponsor Graphile Worker here.

GraphQL Radio Interviews Benjie

Thu, 14 Jul 2022 01:00:00 GMT

2022-07-14

This week, Benjie appears on the revamped GraphQL Radio podcast hosted by Max Stoiber (CEO, Stellate) and Abhi Aiyer (Tech Lead, Gatsby).

They discuss the early days of GraphQL, Benjie's forays into Computer Science as a teenager (and quickly discovering he much preferred to study something else at university!), how he goes about running an open source business with Jem, and the widespread benefits of supporting open source work.

Hear the episode on the GraphQL Radio website.

Jem Discusses OSS Communities at the GitHub ReadME Project

Mon, 04 Jul 2022 01:00:00 GMT

2022-07-04

This week, Jem took part in the GitHub ReadME project, an endeavour to collect stories from open source maintainers and amplify their voices to the wider developer community. The project contains many articles, educational material and podcasts all focused on the developer community.

Click through to the ReadME Project to read a panel interview with Jem alongside Chrissy LeMaire, the creator and maintainer of dbatools, and Fred Schott, the co-creator of Astro.

In this article, Jem discusses how they helped to build the community around Graphile, beginning with the early days of PostGraphile and the growing realization that users wanted an online space to come together to craft plugins and discuss different approaches of Postgres and GraphQL. When the first donations to the project began coming in, they realized it was time to become more intentional in their approach to community building and began drawing inspiration from other open source projects.

Benjie and Jem enjoy working together in open source, and this wouldn't be possible without the sponsorship from the community. By significantly reducing the amount of work needed to achieve business goals, using the Graphile tools results in huge savings for users. If your organization contributes some of these savings back then everyone can benefit from more frequent releases with better performance, better compatibility, better documentation, easier customization, and more features — leading to even greater savings or profits for your organization. Find out how to sponsor Jem and the Graphile suite here.

Schema Metadata: A Growing Need

Tue, 07 Jun 2022 02:00:00 GMT

2022-06-07

This week, Benjie gave a virtual talk at GraphQL Conf - the first official GraphQL Conference hosted by the GraphQL Foundation.

Benjie was one of eight GraphQL experts giving a talk on the cutting edge of GraphQL advancements; his talk focused on the need for a defined approach to GraphQL schema metadata. From complex challenges such as federating schemas to simply indicating pagination limits, the needs for this metadata are growing. This talk surfaced some of the use cases for schema metadata, looked over some of the workarounds that are in use, and briefly explored some proposed solutions.

You can also see the talk on YouTube.

SpecNews - A New GraphQL Podcast from the Graphile team

Tue, 07 Jun 2022 01:00:00 GMT

2022-06-07 by Team Graphile

Benjie and Jem are pleased to announce the release of new podcast SpecNews! A monthly round up of GraphQL Specification news in under ten minutes.

Benjie is a GraphQL TSC member and attends the monthly working groups, he then gives Jem a digest of the two or three hour meeting. He figured, why not make that digest available for everyone?

The podcast is available on Apple podcasts, Spotify, and your favourite podcatcher of choice.

PostGraphile Now Supports GraphQL Over Server-Sent Events

Fri, 15 Apr 2022 01:00:00 GMT

Announced 2022-04-15 by the Graphile Team

PostGraphile now supports GraphQL over Server-Sent Events; a protocol which enables the user to push data to web pages in real-time.

This functionality is powered by graphql-sse - a zero-dependency, HTTP/1 safe, simple, GraphQL over Server-Sent Events Protocol server and client, written by Denis Badurina.

Find his implementation for PostGraphile in the graphile-contrib repo.

Contribute to Graphile projects

This is just one example of a Graphile community member adding to the Graphile suite of open source tools. We welcome contributions in many forms across many of our projects, from simple fixes in our documentation through to community plug-ins and contributions to the main PostGraphile git branch. If you wish to get involved, a good first step is our Contribution Guide; if you wish to get stuck into developing on the main branches of our projects then please pop into our Community Discord where we have several #dev channels - this will let you see where we're currently working in the code base, and ideas others have also had. Pull requests should be focused on changing only one thing at a time - and large changes should seek maintainer approval first. We look forward to welcoming you to our team of contributors!

GraphQL Working Group Discussion

Tue, 07 Dec 2021 01:00:00 GMT

2021-12-07

This week, Benjie appeared on a virtual panel at GraphQL Galaxy - one of the biggest virtual GraphQL conferences.

Benjie was one of five panelists representing the GraphQL Working Group. They discussed their work on the spec, what the working group is and more.

You can also see the discussion on YouTube.

What's Next for the GraphQL Spec in 2022?

Tue, 09 Nov 2021 01:00:00 GMT

2021-11-09

This week, Benjie teamed up with Ivan from Apollo to give a virtual talk looking at the future of the GraphQL Specification at Apollo GraphQL Summit. As long-standing community contributors to the GraphQL Specification Working Group, Ivan and Benjie presented highlights of the 2021 GraphQL Specification release and introduced some of the exciting new features currently working their way towards becoming part of the GraphQL Spec.

The talk is also available on YouTube.

PostGraphile Releases Version 4.12 - Awesome Aggregates

Thu, 27 May 2021 01:00:00 GMT

Announced 2021-05-27 by the Graphile Team

Graphile is pleased to announce the release of PostGraphile version 4.12 - a significant update bringing full support for aggregates.

Awesome Aggregates

We've finally taken our proof of concept aggregation plugin and fleshed it out with some very significant features: calculating aggregates across connections, grouped aggregates, applying conditions to grouped aggregates, ordering by relational aggregates, filtering by the results of aggregates on related connections, and more besides.

For more details see the plugin hosted on GitHub

Release Notes

This release also includes a few small fixes and some other minor features that enable greater community expansion of PostGraphile. We love seeing your plugins - do share them in our #i-made-this channel on Discord or add them to the list on the website!

Full release notes available on GitHub:

Thank you Sponsors

PostGraphile is crowd-funded open-source software, it relies on crowd-sourced funding from individuals and companies to keep advancing.

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. Find out more about sponsorship here on our website.

PostGraphile Releases Version 4.11 - Wonderful Websockets

Fri, 29 Jan 2021 01:00:00 GMT

Announced 2021-01-29 by the Graphile Team

Graphile is pleased to announce the release of PostGraphile version 4.11, an upgrade introducing support for GraphQL websockets, extended support for 'enum tables', native GraphQL schema validation, and fixes in watch mode.

Websocket Support

Thanks to help from author @enisdenjo, PostGraphile 4.11 adds support for the new graphql-ws websocket transport module to replace Apollo's unmaintained subscriptions-transport-ws. It's advised that anyone using websockets with GraphQL move to this new module and protocol.

Opting into this new method also allows the user to perform queries and mutations this way - but the security implications need to be scrutinised first, particularly with respect to cross-site request forgery issues as websockets behave in a different way.

GraphQL Schema Validation

We were surprised to realize that we hadn't yet had PostGraphile validate its GraphQL schema! Fortunately, the schema PostGraphile builds has always been valid, and now we have made sure it checks for this. This means that any bugs in third-party plugins will now be caught before the server goes live.

Other Additions

Support for "enum tables" has been extended to views.
A bug in watch mode (which is not intended for production usage) which could result in pool exhaustion has been resolved.
A minor performance enhancement to pg-sql2 that allows re-use of sql.value nodes for improved PostgreSQL query planning and marginally more efficient queries.
GraphiQL now contains enhancements to the "Merge" functionality

There are also a number of bug fixes, see the release notes for the full details

Thank you

By significantly reducing the amount of work needed to achieve business goals, PostGraphile results in huge savings for users. If your organization contributes some of these savings back then everyone can benefit from more frequent releases with better performance, better compatibility, better documentation, easier customization, and more features — leading to even greater savings or profits for your organization.

More details about how and why to sponsor Graphile are on our Sponsor page.

Full release notes available on GitHub:

Graphile Worker 0.9 Released

Wed, 20 Jan 2021 01:00:00 GMT

Announced 2021-01-20 by the Graphile Team

Today, Graphile Worker 0.9 has been released. This version includes a new events system, a new cron functionality for regularly scheduled jobs and a new job_key_mode setting.

Graphile Worker is a job queue for PostgreSQL running on Node.js. It allows you to run jobs (e.g. sending emails, performing calculations, generating PDFs, etc) "in the background" so that your HTTP response/application code is not held up. Worker can be used with any PostgreSQL-backed application and pairs beautifully with PostGraphile. You can find Worker on GitHub.

New `job_key_mode` setting

When job_key is specified, the job_key_mode setting indicates what should happen when an existing job is found with the same job key. By default the existing job is replaced, but you can also choose to update to the new attributes, or stop and return the existing job. There's more information in the project readme.

Thank you Graphile Sponsors

Graphile Worker is a part of a suite of open source developer tools which we make to address both our needs as developers, and the needs of the wider developer community. This freedom to innovate and make our tooling available for free would not be possible without our sponsors. We have recently joined the GitHub sponsors program and that, alongside Patreon, has been invaluable in giving us paid time to work on open source projects. Take our projects, go make some money, and then give back to help support further development on both Worker and the whole Graphile suite of tools.

Click here to find out more about why and how you should sponsor Graphile.

GitHub Sponsors Now Available to Organizations

Tue, 08 Dec 2020 01:00:00 GMT

Announced 2020-12-08

Many companies depend on open source every day, so it's crucial to invest back into that infrastructure which they have built their businesses upon. So starting today, companies can sponsor projects and developers through their existing billing with GitHub.

Graphile has a number of crowd-funded open-source projects, licensed under the permissive MIT license, including PostGraphile, Graphile Worker, Graphile Migrate and Graphile Starter. Sponsorship increases the rate of fixes, documentation improvements, and feature development on these and other projects.

By significantly reducing the amount of work needed to achieve business goals, using the Graphile tools results in huge savings for users. If your organization contributes some of these savings back then everyone can benefit from more frequent releases with better performance, better compatibility, better documentation, easier customization, and more features — leading to even greater savings or profits for your organization. Join these companies and individuals already sponsoring the Graphile suite.

Read the GitHub Sponsors announcement.

Graphile Migrate Reaches 1.0

Fri, 27 Nov 2020 01:00:00 GMT

Announced 2020-11-27 by the Graphile Team

The Graphile team are pleased to announce that Graphile Migrate 1.0 has been released; after many months of use and testing, Migrate is ready to move from 'experimental' into stable v1.0.0. There are no breaking changes in this release, there is now support for a .gmrc.js file and a few minor fixes.

Graphile Migrate is an opinionated, SQL-powered, productive roll-forward migration tool for Postgres. In true Graphile style, it is simple, familiar, fully functional, configurable and fast: Save a file and the database is updated in milliseconds. There's no custom DSL to learn, use already familiar Postgres syntax. Graphile Migrate pairs well with PostGraphile and the wider Graphile suite of tools. You can find it on GitHub.

Thank you Graphile Sponsors and contributors!

We extend our gratitude to everyone who has filed issues and pull requests against Graphile Migrate ⁠— contributors and user feedback are invaluable to open source projects and help to push the software to be the best possible version of itself it can be. Can you believe that there are currently no open issues or pull requests in this project? We don't expect that to last long!

This freedom to innovate and make our tooling available for free would not be possible without our sponsors. The GitHub Sponsor program has been key in enabling us to spend paid time on our open source work. If you appreciate what we do, encourage your company to sponsor us to help us keep dedicating time and resources to our open source developer tooling. There's more information on our sponsor page.

PostGraphile Releases Version 4.10 - Framework Friends

Fri, 27 Nov 2020 01:00:00 GMT

Announced 2020-11-27 by Team Graphile

Graphile is pleased to announce the release of PostGraphile version 4.10, an upgrade introducing better support for various Node.js webserver frameworks, an upgraded GraphiQL and GraphiQL Explorer, and improvements added by our community members.

Improved Framework Support

The major feature in this release is vastly improved support for various Node.js webserver frameworks, including: Node itself, Connect, Express, Koa, Fastify (v2 and v3), and Restify. This also fixes some long-standing compatibility issues with certain Koa plugins.

To accomplish this, we've split the middleware into separate route handlers for each of our routes, and you can either use the middleware to delegate to these (where the framework allows), or you can add the route handlers directly. You can find documentation in our library usage page and can see examples in our new server examples folder: https://github.com/graphile/postgraphile/tree/v4/examples/servers

Upgraded PostGraphiQL

The GraphiQL upgrade provides a dedicated headers editor panel next to the variables editor, which replaces the old proof-of-concept sidebar. It also adds new "Merge Query" and "Copy Query" buttons to the enhanced GraphiQL which may ease development or debugging flows. The Explorer pane is now much smoother and better looking too!

Community member @eddiewang also added the ability to configure credentials for GraphiQL. We appreciate additions from our community; if you wish to see a particular feature in one of the Graphile projects, we encourage you to open an issue or pull request with details. See our Contribution Guide for some important information before going ahead and writing a new feature.

GraphQL v15

GraphQL v15 compatibility has finally been added - you should review the changes for yourself and pin GraphQL v14 if there are any breaking changes in your projects.

Thank you

As always we want to say a huge THANK YOU to all our sponsors and contributors; This release includes many additions from new and old-hat contributors, and wouldn't have been possible without paid time from our sponsors. 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. Find out more about sponsorship here on our website.

Full release notes

Full detailed technical release notes can be found on GitHub:

Benjie's story at the GitHub ReadME project

Tue, 22 Sep 2020 01:00:00 GMT

2020-09-22

This week, Benjie was profiled by the GitHub ReadME project, a new endeavour to collect stories from open source maintainers and amplify their voices to the wider developer community.

Click through to the ReadME Project to read Benjie's history of software development, starting as a teenager at the turn of the millennium with his own Linux mail server in his bedroom. As he entered the world of employment, he realized he much preferred the freedom of running his own business gave him, and eventually incorporated Graphile with his wife Jem in 2019. Together, they work on Graphile's open source projects and are seeking funding through GitHub Sponsors and Patreon.

In this article, Benjie discusses the ins-and-outs of running an open source company with his wife, while building a supportive community, and sheds light on how other maintainers may start to take their passion project full time.

PostGraphile Releases Version 4.8 - Excellent Enums

Wed, 05 Aug 2020 01:00:00 GMT

Announced 2020-08-05 by the Graphile Team

Graphile is pleased to announce the release of PostGraphile version 4.8.0, an upgrade recommended for all PostGraphile users, which introduces support for enum tables and geometric types.

Enum Tables

PostGraphile now supports "enum tables"; we have previously recommended against using PostgreSQL enums if the enums are ever likely to change after creation. This is because PostgreSQL enums cannot be added to within a transaction, and cannot ever have a value removed.

Instead, we recommend creating a table where the enum value is the primary key, and use foreign key constraints to reference this value.

This functionality is now written inside of PostGraphile. This means you may need to revisit your database permissions if you wish to use this functionality ⁠— don't worry, it only queries the table if it sees the @enum smart comment.

An enum table must have a text (or varchar / char) primary key, and may have other columns. It must be done through using an @enum smart comment (and not a smart tag file or plugin) due to the way in which PostGraphile v4's introspection engine works. See our documentation for more information, or the detailed technical release notes.

All new features

Add support for "enum tables" (GitHub link)
Add support for geometric types (GitHub link)
Warn early if placeholders will be exhausted (GitHub link)
@pgSubscription directive now supports initial events (GitHub link), thank you to @enisdenjo

Further details and full list of fixes in the technical release notes.

The Graphile suite of tools

PostGraphile is just one in a suite of Graphile developer tools. Graphile Worker is a job queue for Postgres running on Node, and Graphile Migrate is an opinionated, SQL-powered, productive roll-forward migration tool for Postgres. In true Graphile style, these tools are simple, familiar, fully functional and fast. Worker, in particular, pairs beautifully with PostGraphile projects, and is currently downloaded over 15k times per week! Together, these projects can give you the building blocks you need to make powerful and performant software quickly and efficiently.

Graphile Starter is a "batteries included" off-the-shelf starter project marrying these tools together with a design system, user and session management and so much more; ready for you to take as a jumping-off point for your own project. You can see our entire suite of projects at our homepage.

Thank you Sponsors!

Dear Sponsors: we love you! Thank you so much for continuing to support us during these difficult pandemic times, the progress of the Graphile projects ⁠— and of course the development of Version 5 ⁠— would not be possible without your support ❤️

PostGraphile Development: work on Version 5 is underway, for more details see the #dev-postgraphile channel on our Discord: https://discord.gg/graphile

Full release notes

Full detailed technical release notes can be found on GitHub:

Graphile Team Releases pgRITA - a Tool for Postgres

Tue, 21 Jul 2020 01:00:00 GMT

Announced 2020-07-21 by Team Graphile

If you've ever thought "I'd love to have the Graphile maintainer checking over my database schema design," then we're extremely excited to share our news with you!

We've built a service (using Graphile Starter) that will analyze your database design against a list of rules we've compiled over the last few years of consultancy and support, explains any detected issues, and in many cases provides tailored SQL fixes to inspire your next migration. Income from this service will help fund Graphile's Open Source endeavours, and what's more, it has a free plan with some essential rules that pair beautifully with PostGraphile.

Recommendations. Insights. Tailored. Actionable.

pgRITA analyzes your database schema against our rules, compiling an interactive report that helps your engineers to build secure, robust and performant databases. Many of our rules produce fixes tailored to your database enabling you to fix missing indexes, constraints, permissions and more in record time.

Really Insightful Technical Appliance

pgRITA compiles an interactive report showing the results of the database analysis, with detailed documentation that explains the potential issues found in the database, and helps engineers determine how to resolve them.

If you're thinking of engaging a database consultant, running pgRITA first could be a great way to reduce costs ─ enabling the consultant to focus in the more bespoke areas where they provide the most value.

View an example report and try the pgRITA demo now.

Graphile Starter 3.0 - Organize your Organizations!

Mon, 27 Apr 2020 01:00:00 GMT

Announced 2020-04-27 by the Graphile Team

The team behind Graphile are excited to release Graphile Starter 3.0 - an updated version of the opinionated quick-start project for full-stack application development in React, Node.js, GraphQL and PostgreSQL. Starter includes the foundations of a modern web application, with a full user registration system, session management, optimized job queue, a significant amount of pre-configured tooling, tests and much more.

Version three of Graphile Starter is focused on organization support. A Starter organization is a group of users (such as a charity, workspace or team) where one user is "in charge" and one person is a billing contact; with support for further permissions configuration. Starter 3.0 includes all the behaviours you'd expect from such a quick start project: creating, deleting and inviting users; inviting non-users; sending and accepting invite emails, re-assigning the ownership or billing contact; managing members; and controlling access to settings based on user role.

Some of the things included with Starter, ready for you to take and extend:

Batteries included: full user system and OAuth with support for organizations or teams, AntD design framework, jest and Cypress end-to-end testing, security, email templating and transport, pre-configured linting and code formatting, deployment instructions, and more

Speedy development: easy debugging, Graphile's idempotent migration system, job queue and server middleware ready to use, hot reloading; not to mention deep integration with VSCode

Type safety: pre-configured type checking, strongly typed throughout with TypeScript

Best practices: React, GraphQL, PostGraphile, Node, jest and Cypress best practices

Full instructions and technical detail can be found on GitHub: Graphile Starter - github.com/graphile/starter

Using Version 3.0

It is intended that you use a "point in time" version of Starter - it's a starting point for your own projects. As such, you can't simply update your existing Starter project to this new version as there's no attempt at backwards compatibility.

Thank you Graphile Sponsors

Graphile Starter has been a labour of love, and would not be possible without our sponsors. We have recently joined the GitHub sponsors program and that, alongside Patreon, has been invaluable in giving us paid time to work on open source projects. Take Graphile Starter, go make some money, and then give back to help support further development on both the Starter and the Graphile suite of tools.

Click here to find out more about why and how you should sponsor PostGraphile development.

Graphile Migrate 0.1 Released

Tue, 17 Mar 2020 01:00:00 GMT

Announced 2020-03-17 by Team Graphile

The Graphile team are pleased to announce that Graphile Migrate 0.1 is out in pre-release. This is a big milestone for the project, with it finally leaving 0.0.x territory and leaving behind the word "highly" in the phrase "highly experimental"! This release is a significant jump from the previous versions and includes many new commands, more configuration options, as well as a suite of new features.

Graphile Migrate is an opinionated, SQL-powered, productive roll-forward migration tool for Postgres. In true Graphile style, it is simple, familiar, fully functional and fast: Save a file and the database is updated in milliseconds. There's no custom DSL to learn, instead use standard Postgres syntax. Graphile Migrate pairs well with PostGraphile and the wider Graphile suite of tools. You can find it on GitHub.

Migrate 0.1 features

There are many new features and a 🚨 breaking change in Migrate 0.1. Make sure you read the full release notes and the new and improved Readme of the project on GitHub.

New commands:
- init to set up a new environment
- compile to compile an SQL file (filling out placeholders) and output the result
- run to compile and run an SQL file
- completion to install CLI autocompletion
More configuration options are exposed
Support for the current migration to be a directory
Support for naming commits
Ability to run afterRest SQL actions as a superuser
Add ability to run graphile-migrate status without requiring a database connection
Stronger linting, stronger types and lots of other housekeeping
🚨 potential checksum breaking change

The full, technical details can be found in the release notes in the project repo.

Thank you Graphile Sponsors and contributors!

Graphile Worker 0.4 released

Wed, 05 Feb 2020 01:00:00 GMT

Announced 2020-02-05 by Team Graphile

Today, Graphile Worker 0.4 has been released. This version includes significantly enhanced performance gains, a dedicated API for queuing jobs from TypeScript, and the ability to run jobs in parallel.

Full release notes

The full, technical details can be found in the release notes in the project repo.

Thank you Graphile Sponsors

Click here to find out more about why and how you should sponsor Graphile.

Graphile goes to FOSDEM

Fri, 31 Jan 2020 01:00:00 GMT

2020-01-31

Benjie and Jem are excited to be representing the Graphile suite of tools at this years FOSDEM in Brussels. FOSDEM is Europe's largest community conference focussed on Open Source software, providing software developers and communities a place to meet, get in touch with other developers, find out about the latest developments in the free software world and attend talks and presentations on various topics from project leaders.

The team had an amazing experience at FOSDEM in 2019 and are looking forward to meeting thousands of members of the open source community again. Send a message if you are going so we can arrange to meet!

More details about FOSDEM available on their website.

Graphile Starter is here!

Tue, 03 Dec 2019 01:00:00 GMT

Announced 2019-12-03 by Team Graphile

The team behind Graphile are excited to release Graphile Starter - an opinionated quick-start project for full-stack application development in React, Node.js, GraphQL and PostgreSQL. It includes the foundations of a modern web application, with a full user registration system, session management, optimized job queue, a significant amount of pre-configured tooling, tests and much more.

Graphile Starter is designed for client projects, hack days, side hustles, SaaS projects, and many other uses we haven't even thought of yet. The boilerplate for a React, GraphQL and Postgres stack is already there, just add your idea and you're ready to go.

Some of the things included with the starter, ready for you to take and extend:

Batteries included: full user system and OAuth, AntD design framework, jest and Cypress end-to-end testing, security, email templating and transport, pre-configured linting and code formatting, deployment instructions, and more

Speedy development: easy debugging, Graphile's idempotent migration system, job queue and server middleware ready to use, hot reloading; not to mention deep integration with VSCode: plugin recommendations, preconfigured settings, ESLint and Prettier integration and debugging profiles

Type safety: pre-configured type checking, strongly typed throughout with TypeScript

Best practices: React, GraphQL, PostGraphile, Node, jest and Cypress best practices

Full instructions and technical detail can be found on GitHub: github.com/graphile/starter

Thank you Graphile Sponsors

Click here to find out more about why and how you should sponsor PostGraphile development.

PostGraphile Releases Version 4.5 - Explain Feature

Sun, 24 Nov 2019 00:00:01 GMT

Announced 2019-11-24

Graphile is pleased to announce the release of PostGraphile version 4.5.0, an upgrade recommended for all PostGraphile users.

🚨Beware: previously the CLI would ignore arguments it didn't understand, now it exits stating the arguments it wasn't expecting. If you were relying on this old behaviour, you will need to update your code to pass valid arguments.

New Feature: Explain in GraphiQL

The headline feature in 4.5 is the addition of the new Explain feature in GraphiQL, visible by using the --allow-explain flag. In GraphiQL you'll see a new section in your return statement, plus new panel on the right which will show executed query in a readable format.

Smart Tags

No longer do you need to put COMMENT commands in the database ("smart comments") to customize your schema, you can now use a tags file to gather these "smart tags" into one, version controlled, easy-to-diff place. Smart comments and smart tags can be used in unison, and both will be supported going forward so you can pick whichever works best for your team.

Big contributions from the Graphile community

Thanks to everyone in the Graphile community who has contributed to this release; it's been a good release for community involvement as you can see in the release notes. Contributions from the community include improvements to QueryBuilder, better JWT support and bug fixes for types.

Thank you for your sponsorship

We now have 84 sponsors across GitHub and Patreon and that means we're funded to spend an average of nearly 2 days per week on Open Source; this is brilliant!

Click here to find out more about why and how you should sponsor PostGraphile development.

Full release notes

Full detailed technical release notes can be found on GitHub:

Increasing velocity with GraphQL and Postgres

Mon, 04 Nov 2019 01:00:00 GMT

2019-11-04

Benjie and Jem travelled to Prague for ReactiveConf where Benjie gave the keynote on increasing velocity with GraphQL and Postgres. The talk focused on how the two tools can pair beautifully, leading to massively increased software development and delivery speed, faster APIs, fewer bugs and ultimately enabling a greater focus on delivering value on the frontend rather than maintaining three different layers of data models and associated logic on the backend.

You can also view the talk on YouTube here.

PostGraphile Releases Version 4.4 - Real-time!

Fri, 03 May 2019 00:00:01 GMT

Announced 2019-05-03 by the Graphile Team

Graphile is pleased to announce the release of PostGraphile version 4.4.0, a backwards-compatible* upgrade recommended for all PostGraphile users.

The headline feature in 4.4 is real-time support. Previously, GraphQL subscriptions were only available in PostGraphile via the “supporter” plugin (for Patreon sponsors). We’ve overhauled this functionality and released it as open source, added built-in support for subscriptions to our PostGraphiQL editor, and also added experimental support for live queries.

Besides these exciting features, a lot of improvements and minor features have been added, including: performance improvements; revised handling of PostgreSQL restarts and server availability on startup; having makeExtendSchemaPlugin do more for you automatically; giving you a way to choose between lists and Relay connections on a per-table, per-function or per-constraint basis; and adding a plugin dependency/ordering system.

PostGraphile is crowd-funded open-source software, it relies on financial contributions from the individuals and companies that are using it in order to keep advancing. Please sponsor the project, you will surely reap the rewards!

Technical details of this release can be found in the release notes, or read on for more information on Subscriptions and Live Queries.

* there’s a small number of fixes which may cause issues for existing applications that were relying on broken behaviour, these are outlined in the “Breaking Fixes” section of the release notes, along with how to opt-out of these fixes.

GraphQL Subscriptions

GraphQL Subscriptions are an official feature, detailed in the GraphQL specification. They enable your application to request a certain query be performed whenever the specified event occurs on the GraphQL server, for example emailReceived, userStatusChanged, notificationAdded, or messageArchived.

To enable this real-time feature, a long running connection is required with the server. In PostGraphile we achieve this via websockets, the de-facto standard for real-time GraphQL targeting web browsers and mobile apps.

Note: with a standard GraphQL subscription, the query is only executed when the specified event occurs, making it an efficient way of subscribing to particular events without being notified of every data change on the backend.

Subscriptions are the recommended way of adding real-time features to your GraphQL API.

PostGraphile Live Queries

A “live query” monitors the query a user provides and gives the client an updated version whenever the query would return a different result. You can think of it as akin to extremely frequent polling of a regular query, but without the bandwidth costs. Live queries are not yet an official feature of GraphQL, and so there are a number of different implementations. PostGraphile’s live queries do not require specific client software since we use the standard GraphQL subscriptions interface — simply change your query to a subscription and it becomes live, as in the following example (available on GitHub) showing real-time points rankings of fictional players:

Live queries are an incredibly powerful tool for frontend developers, as it means they don’t need to worry about monitoring for changes in the data — they know the data they’ve requested will always be up to date. However, live queries are not a panacea: they can come with significant backend cost and/or complexity.

PostGraphile has worked hard to decrease the costs associated with live queries, but there’s still more to be done. Currently we feel PostGraphile live queries may be suitable in apps with relatively small user bases (such as for internal tooling used across a large enterprise), but if you’re targeting an internet scale deployment hoping for millions of users you will likely be better off using traditional subscriptions (or keeping live queries to a very small area of your application). There are lots of factors that may go into deciding if live queries are a good fit for your problem; if you need help deciding then you may wish to engage our consultancy services.

There will be more enhancements in live queries in future. If you're interested in helping in this development please get in touch via our Discord chat.

Help us to help you!

Huge thanks to the 70 individuals and companies already sponsoring PostGraphile!

Click here to find out more about why and how you should sponsor PostGraphile development.

Full release notes

As always, we’ve published detailed technical release notes to GitHub:

PostGraphile Releases Version 4.1 - Better Webpackability!

Thu, 06 Dec 2018 00:00:01 GMT

The original GraphQL API for PostgreSQL: now with improved Lambda support

Announced 2018-12-06 by Team Graphile

Building upon the huge performance gains found in Version 4, Graphile is pleased to announce the release of Version 4.1 of PostGraphile, now with a huge improvement to startup performance in serverless environments. This update also brings a large number of enhancements including much broader PostgreSQL function support, an enhanced GraphiQL interface, and a lot more helpers for writing plugins.

See the entire release notes on GitHub.

Better webpackability

Thanks to funding from Connecting Good, PostGraphile Version 4.1 enhances startup performance for webpack and serverless/Amazon Lambda users:

Bundle size is around 10 times smaller
Unzip time is up to 140 times faster
Cold start time is now under half a second

This has been achieved through targeted work optimising PostGraphile’s "webpackability" - how well it could be processed by the popular webpack tool. Previously, many features of PostGraphile could not be included in webpack's output, resulting in >4000 files to be zipped up and sent to Lambda. Now a PostGraphile application can be reduced to just 2 files, leading to a smaller zip file and a faster startup time.

Do you use PostGraphile in serverless environments? If so, make sure to update to Version 4.1 and let us know about your performance gains.

Big contributions from the Graphile community

Version 4.1 also includes a big update from frequent contributor @mattbretl, who has introduced support for a wider range of PostgreSQL functions. This reduces the constraints developers have to work within, freeing them to use the right PostgreSQL function type for the task, leading to even faster development times.

Help us to help you!

PostGraphile is crowd-funded open-source software, it relies on crowd-sourced funding from individuals and companies to keep advancing.

By significantly reducing the amount of work needed to achieve business goals, PostGraphile results in huge savings for users. Your organization should contribute some of these savings back so everyone can benefit from more frequent releases with better performance, better compatibility, better documentation, easier customization, and more features - leading to even greater savings or profits for your organization.

Huge thanks to the 60 individuals and companies already sponsoring PostGraphile!

Click here to sponsor PostGraphile development now.

GraphQL Finland

Tue, 23 Oct 2018 01:00:00 GMT

2018-10-23

Benjie travelled to GraphQL Finland to give a talk on Database-Driven GraphQL Development. Learn how a database-centric approach to GraphQL API development can give your engineers more time to focus on the important parts of your application. Topics covered included authorization, adhering to GraphQL best practices, embracing the power of PostgreSQL, and avoiding common pitfalls.

You can also find the talk on YouTube here.

PostGraphile Launches Version 4

Tue, 02 Oct 2018 00:00:01 GMT

Announced 2018-10-02 by Team Graphile

The original GraphQL API for PostgreSQL: now vastly more performant, customizable and extensible than ever before

After a year of development and testing, Benjie is pleased to announce the release of PostGraphile Version 4 ⁠— the most customizable and extensible automatic GraphQL API for PostgreSQL yet. PostGraphile⁠—previously known as PostGraphQL⁠—has been re-written from the ground up with a strong focus on performance, best practices and flexibility. This has been enabled through the creation of Graphile Engine - a powerful datasource-agnostic GraphQL Engine that has extensibility and performance at its core ⁠— upon which PostGraphile Version 4 is built.

Instead of requiring developers to learn a new set of tools and lock business logic into a new software stack, PostGraphile encourages them to build the important things⁠—their data and business logic—using the database they're already using. Then with minimal configuration, they can use PostGraphile to make this available as a secure and lightning-fast GraphQL API.

PostGraphile Version 4 is highly performant

Benjie has rebuilt the core of PostGraphile entirely, with a strong focus on performance. Unlike other solutions, PostGraphile is able to look at the GraphQL query holistically and find the most efficient way of executing it. This has lead to a large increase in the request throughput, and a 94% decrease in latency. Peak memory usage has also reduced by 92% as compared to Version 3. The result is a much faster application, and happier end users ⁠— especially those on mobile. PostGraphile Version 3 developers will be able to reap these massive performance improvements simply by updating ⁠— no need to change their application code.

Version 4 is highly customizable

Version 4 has added three handy features to help developers streamline their GraphQL schema. First, unnecessary functionality from PostgreSQL extensions is automatically filtered out by default, so only the tables and functions the developer has added are exposed. Secondly, PostGraphile can now inspect database permissions, and automatically remove types and fields from the generated schema the end user has no way of accessing. Finally, Version 4 introduces the concept of "smart comments".

The new smart comments functionality enables the developer to customize their GraphQL schema as they see fit. By adding smart comments, the developer can easily perform operations such as renaming fields without modifying the underlying table structure. Besides renaming fields, current operations include renaming types, detailing when a field should be included or not (e.g. making a field read-only), and handling deprecation gracefully. Plugin authors are already using the smart comments functionality to add new features to their PostGraphile schemas, such as adding relations on views.

These features lead to smaller GraphQL schemas that are easier for developers to understand and manage without sacrificing desired functionality.

Version 4 is highly extensible

Before commencing work on PostGraphile Version 4, Benjie reviewed every issue in the PostGraphile bug tracker, and concluded that a rigid one-size-fits all GraphQL API was too restrictive for many users. The rigid nature of Version 3 resulted in a number of users having to compromise with workarounds such as schema stitching, or resort to maintaining a separate fork of the project to add their desired functionality. With this in mind Benjie, set out to find a solution to all these issues.

PostGraphile became a modular project, with its GraphQL generation powered by a new plugin-based project named Graphile Engine. Users can now use plugins to add functionality to their GraphQL schema without requiring modifications to the core ⁠— and they can even share these features with the world. During the development stages of Graphile Engine, a community of plugin authors formed; with their help, the plugin system solidified into the capable production-ready system that Benjie is proud to be releasing today. This work has negated the need to maintain forks of PostGraphile, and has lead to a growing ecosystem of functionality putting PostGraphile at the forefront of PostgreSQL GraphQL APIs.

PostGraphile is open source, supported by the community

This release of PostGraphile wouldn’t have been possible without the community. Benjie says, “The community's response to PostGraphile has been amazing! People have found so many ways to help support the project: from testing and reporting issues, to documentation fixes, and even large feature development. Their sponsorship now funds one day a week dedicated to PostGraphile development, and this support is growing every month which is already leading to more features and faster releases. This voluntary financial support from the community is very motivational, a great antidote to the burn-out that's common in open source maintainers, and it's exciting to be turning PostGraphile into a sustainable open source project that people can rely on for years to come. It's also wonderful to see the community being so supportive of each other ⁠— sharing knowledge, debugging issues, testing and sharing plugins. There's so much more to come from PostGraphile ⁠— bring on the future!”

Graphile News

PostGraphile and Grafast release candidate!

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

Why this is still a release candidate

Thinking in plans

Read more

Thank you Sponsors

Grafast beta: last epic solved!

Polymorphism epic achieved

TypeDefs / plans overhaul

Grafast features

New steps

Step classes

Grafserv

Improved type-safety

Other breaking changes

Bug fixes

And here’s the rest...

Thank you Sponsors

Major Grafast beta: three down, one to go

Input evaluation moved to runtime

What does this mean for my codebase?

Change fieldArgs.get to fieldArgs.getRaw

Converting applyPlan and inputPlan

No more $step.eval*()

ExecutableStep renamed to Step

PostGraphile changes

SQL generation moved to runtime

SQL efficiency increased

Postgres Arrays now parse 5x faster

Easier to write SQL fragments

Additional changes

makeGrafastSchema

graphile-export

Improved plan diagrams

Step classes

Other Grafast improvements

Thank you Sponsors

PostGraphile V5 public beta — get involved!

Intro to V5

Sponsor the project

Intro to PostGraphile V5 — a new blog series!

PostGraphile V5 Sponsors Early Access

Thank you for sponsoring the project!

Step Aside Resolvers: a New Approach to GraphQL Execution

Development Support Now Available

Graphile Worker 0.14 - Batch Jobs

Batch Jobs

Other Features

Sponsor the project

GraphQL Radio Interviews Benjie

Jem Discusses OSS Communities at the GitHub ReadME Project

Schema Metadata: A Growing Need

SpecNews - A New GraphQL Podcast from the Graphile team

PostGraphile Now Supports GraphQL Over Server-Sent Events

Contribute to Graphile projects

GraphQL Working Group Discussion

What's Next for the GraphQL Spec in 2022?

PostGraphile Releases Version 4.12 - Awesome Aggregates

Awesome Aggregates

Release Notes

Thank you Sponsors

PostGraphile Releases Version 4.11 - Wonderful Websockets

Websocket Support

GraphQL Schema Validation

Other Additions

Thank you

Graphile Worker 0.9 Released

New job_key_mode setting

Thank you Graphile Sponsors

GitHub Sponsors Now Available to Organizations

Graphile Migrate Reaches 1.0

Thank you Graphile Sponsors and contributors!

PostGraphile Releases Version 4.10 - Framework Friends

Improved Framework Support

Upgraded PostGraphiQL

GraphQL v15

Thank you

Full release notes

Benjie's story at the GitHub ReadME project

Change `fieldArgs.get` to `fieldArgs.getRaw`

Converting `applyPlan` and `inputPlan`

No more `$step.eval*()`

New `job_key_mode` setting