April 14, 2025

What's new in GraphQL-Ruby 2.5

Hey everyone,

I hope this update finds you well. GraphQL-Ruby v2.5 is now available on Rubygems and this is just a note to share some new things you'll find since my last update:

• Tracing: two new developments here. There's a new detailed tracer for producing in-depth traces of GraphQL execution. You can run it on a sample of production traffic, then use Google's Perfetto viewer to inspect traces. (Producing these trace artifacts was really interesting. I wrote a little about it.) Since these traces are GraphQL-focused, I think they provide more depth and a give a better overview of what's happening from a GraphQL perspective.

  Additionally, all of GraphQL-Ruby's built-in APM integrations have been updated to greatly improve Dataloader support (namely, they trace Source#fetch calls and they pause spans when a Ruby Fiber pauses) and to make it easier to opt out of resolve_type and authorized? spans. If you're not using those spans, you can disable them with trace_with ... resolve_resolve_type: false, resolve_authorized: false -- and doing so might save you some money with your APM provider.

• Fetching data with Rails has gotten some new first-class support with GraphQL::Dataloader:

  • dataload_record(ModelClass, id) fetches a single record.
  • dataload_association(record, :association_name) fetches an associated record from a parent.
  • dataload(YourSource, key) is shorthand for dataloader.with(...).load(...).

  You can find more details about these methods in the API docs. Even if you already have a good Rails setup, I recommend checking out the implementation of those Dataloader sources to see if you can improve your custom ones (or upstream some improvements!).

• Breaking changes and deprecations have been included to get GraphQL-Ruby closer to the GraphQL spec in several cases:

  • Subscriptions: previous versions of GraphQL-Ruby allowed subscription { ... } operations to include multiple top-level selections (i.e., a client could subscribe to multiple events at once). However, this is against the GraphQL-spec, and frankly, it's impractical. GraphQL-Ruby v2.5 validates that subscriptions only have a single top-level field.
  • Validation: Previously, GraphQL-Ruby accidentally allowed queries which selected union-typed fields but didn't make any subselections. This is invalid according to the spec, but since your API may already have traffic using this pattern (by mistake, presumably), v2.5 emits a warning by default and includes a migration path for finding uses of this in production and switching your schema over.
  • Validation, again: Previously, GraphQL-Ruby didn't apply the spec's validation that, if a query requested two scalar fields in typed fragments (e.g., on a union), then those fields' types must match. v2.5 emits a warning when this case is encountered and includes a migration path for handling this scenario in production and opting into the future default.
  • Query complexity: Several bugs in this calculation have been fixed, but they may result in higher complexity scores than were previously calculated. The legacy behavior is maintained by default, and a corrected calculation is available for opt-in. You can also compare scores in test, development, and production to see if/how this change affects your schema. More in the API Docs.

Of course, there's a long tail of fixes and features in the CHANGELOG, too.

Finally, a quick reminder that a recent security flaw was discovered in many GraphQL-Ruby versions last month. It affected loading GraphQL schemas from JSON, including usage via the GraphQL-Client library. If you haven't already updated to a patched version, please check out the advisory on GitHub and update!

Best,

Robert