GraphQL::PersistedQueries

GraphQL::PersistedQueries is the implementation of persisted queries for graphql-ruby. With this plugin your backend will cache all the queries, while frontend will send the full query only when it's not found at the backend storage.

• 🗑Heavy query parameter will be omitted in most of cases – network requests will become less heavy
• 🤝Clients share cached queries – it's enough to miss cache only once for each unique query
• 🎅Works for clients without persisted query support

Used in production by:

• Yammer by Microsoft
• Toptal
• Want to be here? Let me know 🙂

You can support my open–source work here.

Getting started

First of all, install and configure apollo's persisted queries on the front–end side:

import { HttpLink, InMemoryCache, ApolloClient } from "@apollo/client";
import { createPersistedQueryLink } from "@apollo/client/link/persisted-queries";
import { sha256 } from 'crypto-hash';

const httpLink = new HttpLink({ uri: "/graphql" });
const persistedQueriesLink = createPersistedQueryLink({ sha256 });
const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: persistedQueriesLink.concat(httpLink);
});

Add the gem to your Gemfile gem 'graphql-persisted_queries' and add the plugin to your schema class:

class GraphqlSchema < GraphQL::Schema
  use GraphQL::PersistedQueries
end

Pass :extensions argument as part of a context to all calls of GraphqlSchema#execute, usually it happens in GraphqlController, GraphqlChannel and tests:

GraphqlSchema.execute(
  params[:query],
  variables: ensure_hash(params[:variables]),
  context: {
    extensions: ensure_hash(params[:extensions])
  },
  operation_name: params[:operationName]
)

You're all set!

Compiled queries (increases performance up to 2x!)

When query arrives to the backend, GraphQL execution engine needs some time to parse it and build the AST. In case of a huge query it might take a lot of time. What if we cache the AST instead of a query text and skip parsing completely? The only thing you need to do is to turn :compiled_queries option on:

class GraphqlSchema < GraphQL::Schema
  use GraphQL::PersistedQueries, compiled_queries: true
end

Using this option might make your endpoint up to 2x faster according to the benchmark.

Heads up! This feature only works on graphql-ruby 1.12.0 or later, but I guess it might be backported.

Advanced usage

All the queries are stored in memory by default, but you can easily switch to another storage (e.g., redis:

class GraphqlSchema < GraphQL::Schema
  use GraphQL::PersistedQueries, store: :redis, redis_client: { redis_url: ENV["MY_REDIS_URL"] }
end

We currently support memory, redis, redis_with_local_cache and memcached out of the box. The detailed documentation can be found here.

When the error occurs, the gem tries to not interrupt the regular flow of the app (e.g., when something is wrong with the storage, it will just answer that persisted query is not found). You can add a custom error handler and try to fix the problem or just log it.

Since our queries are slim now, we can switch back to HTTP GET, you can find a guide here.

batch-link allows to group queries on the client side into a single HTTP request before sending to the server. In this case you need to use GraphqlSchema.multiplex(queries) instead of #execute. The gem supports it too, no action required!

persisted-queries-link uses SHA256 for building hashes by default. Check out this guide if you want to override this behavior.

It is possible to skip some parts of the query lifecycle for cases when query is persisted - read more here.

An experimental tracing feature can be enabled by setting tracing: true when configuring the plugin. Read more about this feature in the Tracing guide.

📖 Read more about the gem internals: Persisted queries in GraphQL: Slim down Apollo requests to your Ruby application

Credits

Initially sponsored by Evil Martians.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/DmitryTsepelev/graphql-ruby-persisted_queries.

License

The gem is available as open source under the terms of the MIT License.