graphql-ruby — Ruby Library for Building GraphQL Servers

Introduction

graphql-ruby is the dominant GraphQL library for the Ruby ecosystem, used by GitHub, Shopify, and many other organizations to power their GraphQL APIs. It provides a class-based, object-oriented API for defining GraphQL schemas that feels natural to Ruby developers. The library handles the full GraphQL lifecycle and integrates deeply with Ruby on Rails while remaining usable in any Ruby application.

What graphql-ruby Does

• Defines GraphQL schemas using Ruby classes with an intuitive DSL for types, fields, and arguments
• Executes queries with automatic field resolution that maps to Ruby methods
• Supports subscriptions with pluggable backends including ActionCable, Pusher, and Ably
• Provides built-in authorization framework for field-level and object-level access control
• Generates Relay-compatible connections and pagination for list fields

Architecture Overview

graphql-ruby uses a class-based type system where each GraphQL type is a Ruby class inheriting from a base type (Object, InputObject, Enum, Interface, Union, Scalar). Fields are declared with the field DSL method, and resolvers are plain Ruby methods on the type class. The schema class ties everything together and serves as the entry point for query execution. Internally, the library compiles the type definitions into an optimized execution structure. Query execution uses a fiber-based interpreter that supports lazy resolution, batching via dataloader, and concurrent field evaluation.

Self-Hosting & Configuration

• Add gem "graphql" to your Gemfile and run bundle install
• In Rails, run rails generate graphql:install to scaffold the schema, base types, and controller
• Define types as Ruby classes in app/graphql/types/ following Rails conventions
• Configure the schema class with settings for max depth, max complexity, and error handling
• Add subscription support by configuring an ActionCable or Pusher backend in the schema

Key Features

• Class-based type system that leverages Ruby's object model for clean, maintainable schema definitions
• Built-in dataloader for batching database queries and avoiding N+1 problems
• Authorization framework with authorized? hooks on types and fields for access control
• Relay-compatible connection types with automatic cursor-based pagination
• Pro features available for large-scale deployments including persisted queries, operation store, and dashboard

Comparison with Similar Tools

• graphql-js — the JavaScript reference implementation; graphql-ruby adapts the same concepts to Ruby's object-oriented style
• Absinthe (Elixir) — the Elixir GraphQL library with a similar quality focus; graphql-ruby targets the Ruby ecosystem with Rails-specific integrations
• graphql-java — the JVM equivalent; graphql-ruby uses Ruby classes instead of Java builders for schema definition
• Strawberry (Python) — uses Python dataclasses and type hints; graphql-ruby uses Ruby classes and a field DSL
• Juniper (Rust) — uses Rust macros for type-safe schemas; graphql-ruby relies on Ruby's dynamic features for flexibility

FAQ

Q: Is graphql-ruby used in production at scale? A: Yes. GitHub's public API is powered by graphql-ruby, serving millions of queries daily. Shopify, Flexport, and many other companies also use it in production.

Q: How does authorization work? A: Each type and field can define an authorized? method that checks whether the current user has permission to access that resource. Unauthorized fields return nil or raise errors depending on your configuration.

Q: Does graphql-ruby support file uploads? A: Yes. The library supports the GraphQL multipart request specification for file uploads. In Rails, uploaded files are available through the standard ActionDispatch file handling.

Q: What is the graphql-ruby Pro license? A: The core graphql-ruby gem is open source under the MIT license. A separate Pro package with advanced features (persisted queries, operation store, Pundit integration) requires a commercial license.

Sources

• https://github.com/rmosolgo/graphql-ruby
• https://graphql-ruby.org/