rails-graphql

alec-c4's avatarfrom alec-c4

GraphQL specialist for Rails applications. Use when building GraphQL schemas, resolvers, mutations, subscriptions, or implementing DataLoader for N+1 prevention. Alternative to REST APIs with flexible querying capabilities.

⭐18stars🔀1forks📁View on GitHub🕐Updated Nov 11, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill is a comprehensive specialist for architecting and implementing GraphQL APIs within Ruby on Rails environments. It streamlines the transition from REST to GraphQL by providing expert guidance on schema design, efficient data fetching, and real-time updates. By focusing on performance optimization through DataLoader and robust security patterns, it helps developers build scalable, flexible, and well-tested API layers that follow industry best practices.

Use Cases

  • Designing complex GraphQL schemas and type definitions that map seamlessly to Rails ActiveRecord models.
  • Implementing DataLoader patterns to solve N+1 query performance issues in deeply nested data fetches.
  • Building secure mutations for data creation and updates with integrated authentication and Pundit-based authorization.
  • Setting up real-time communication channels using GraphQL subscriptions for live data updates.
  • Developing automated RSpec test suites to ensure the reliability and correctness of GraphQL endpoints and resolvers.
namerails-graphql
descriptionGraphQL specialist for Rails applications. Use when building GraphQL schemas, resolvers, mutations, subscriptions, or implementing DataLoader for N+1 prevention. Alternative to REST APIs with flexible querying capabilities.

Rails GraphQL Specialist

Build flexible, efficient GraphQL APIs with Rails.

When to Use This Skill

  • Creating GraphQL schemas and types
  • Implementing query resolvers
  • Building mutations (create, update, delete)
  • Setting up subscriptions (real-time updates)
  • Preventing N+1 queries with DataLoader
  • GraphQL authentication and authorization
  • Query complexity analysis
  • Testing GraphQL endpoints

Setup

# Gemfile
gem 'graphql'
gem 'graphiql-rails', group: :development  # GraphQL IDE

# Install
bundle install
rails generate graphql:install

# This creates:
# app/graphql/
#   types/
#   mutations/
#   my_app_schema.rb
# app/controllers/graphql_controller.rb

Schema Design

Type Definitions

# app/graphql/types/user_type.rb
module Types
  class UserType < Types::BaseObject
    description "A user in the system"

    field :id, ID, null: false
    field :email, String, null: false
    field :name, String, null: true
    field :avatar_url, String, null: true
    field :created_at, GraphQL::Types::ISO8601DateTime, null: false

    # Associations
    field :posts, [Types::PostType], null: true
    field :comments, [Types::CommentType], null: true

    # Computed fields
    field :posts_count, Integer, null: false

    def posts_count
      object.posts.count
    end

    def avatar_url
      object.avatar.attached? ? Rails.application.routes.url_helpers.url_for(object.avatar) : nil
    end
  end
end

Query Type

# app/graphql/types/query_type.rb
module Types
  class QueryType < Types::BaseObject
    # Single resource
    field :user, Types::UserType, null: true do
      description "Find a user by ID"
      argument :id, ID, required: true
    end

    def user(id:)
      User.find_by(id: id)
    end

    # Collection with pagination
    field :users, [Types::UserType], null: false do
      description "List all users"
      argument :limit, Integer, required: false, default_value: 20
      argument :offset, Integer, required: false, default_value: 0
      argument :search, String, required: false
    end

    def users(limit:, offset:, search: nil)
      scope = User.all
      scope = scope.where("name ILIKE ?", "%#{search}%") if search.present?
      scope.limit(limit).offset(offset)
    end

    # Current user
    field :me, Types::UserType, null: true do
      description "Get currently authenticated user"
    end

    def me
      context[:current_user]
    end
  end
end

Mutations

Base Mutation

# app/graphql/mutations/base_mutation.rb
module Mutations
  class BaseMutation < GraphQL::Schema::RelayClassicMutation
    argument_class Types::BaseArgument
    field_class Types::BaseField
    input_object_class Types::BaseInputObject
    object_class Types::BaseObject

    def current_user
      context[:current_user]
    end

    def authenticate!
      raise GraphQL::ExecutionError, "Authentication required" unless current_user
    end

    def authorize!(record, action)
      policy = Pundit.policy!(current_user, record)
      raise GraphQL::ExecutionError, "Not authorized" unless policy.public_send("#{action}?")
    end
  end
end

Create Mutation

# app/graphql/mutations/create_post.rb
module Mutations
  class CreatePost < BaseMutation
    description "Create a new post"

    argument :title, String, required: true
    argument :body, String, required: true
    argument :published, Boolean, required: false, default_value: false

    field :post, Types::PostType, null: true
    field :errors, [String], null: false

    def resolve(title:, body:, published:)
      authenticate!

      post = current_user.posts.build(
        title: title,
        body: body,
        published: published
      )

      if post.save
        # Trigger subscription
        MyAppSchema.subscriptions.trigger('postCreated', {}, post)

        { post: post, errors: [] }
      else
        { post: nil, errors: post.errors.full_messages }
      end
    end
  end
end

Update Mutation

# app/graphql/mutations/update_post.rb
module Mutations
  class UpdatePost < BaseMutation
    argument :id, ID, required: true
    argument :title, String, required: false
    argument :body, String, required: false
    argument :published, Boolean, required: false

    field :post, Types::PostType, null: true
    field :errors, [String], null: false

    def resolve(id:, **attributes)
      authenticate!

      post = Post.find(id)
      authorize!(post, :update)

      if post.update(attributes.compact)
        { post: post, errors: [] }
      else
        { post: nil, errors: post.errors.full_messages }
      end
    rescue ActiveRecord::RecordNotFound
      { post: nil, errors: ["Post not found"] }
    end
  end
end

Delete Mutation

# app/graphql/mutations/delete_post.rb
module Mutations
  class DeletePost < BaseMutation
    argument :id, ID, required: true

    field :success, Boolean, null: false
    field :errors, [String], null: false

    def resolve(id:)
      authenticate!

      post = Post.find(id)
      authorize!(post, :destroy)

      if post.destroy
        { success: true, errors: [] }
      else
        { success: false, errors: post.errors.full_messages }
      end
    rescue ActiveRecord::RecordNotFound
      { success: false, errors: ["Post not found"] }
    end
  end
end

DataLoader (N+1 Prevention)

Record Loader

# app/graphql/loaders/record_loader.rb
module Loaders
  class RecordLoader < GraphQL::Dataloader::Source
    def initialize(model, column: model.primary_key, where: nil)
      @model = model
      @column = column.to_s
      @column_type = model.type_for_attribute(@column)
      @where = where
    end

    def fetch(keys)
      records = @model.where(@column => keys)
      records = records.merge(@where) if @where

      key_to_record = records.index_by { |record| @column_type.cast(record.public_send(@column)) }
      keys.map { |key| key_to_record[@column_type.cast(key)] }
    end
  end
end

Association Loader

# app/graphql/loaders/association_loader.rb
module Loaders
  class AssociationLoader < GraphQL::Dataloader::Source
    def initialize(model, association_name)
      @model = model
      @association_name = association_name
    end

    def fetch(records)
      ActiveRecord::Associations::Preloader.new(
        records: records,
        associations: @association_name
      ).call

      records.map { |record| record.public_send(@association_name) }
    end
  end
end

Usage in Types

module Types
  class PostType < Types::BaseObject
    field :author, Types::UserType, null: false

    def author
      # Instead of: object.author (causes N+1)
      dataloader.with(Loaders::RecordLoader, User).load(object.user_id)
    end

    field :comments, [Types::CommentType], null: false

    def comments
      # Instead of: object.comments (causes N+1)
      dataloader.with(Loaders::AssociationLoader, Post, :comments).load(object)
    end
  end
end

Subscriptions

Subscription Type

# app/graphql/types/subscription_type.rb
module Types
  class SubscriptionType < Types::BaseObject
    field :post_created, Types::PostType, null: false do
      description "Subscribe to new posts"
      argument :author_id, ID, required: false
    end

    def post_created(author_id: nil)
      return object unless author_id
      object if object.user_id.to_s == author_id
    end

    field :comment_added, Types::CommentType, null: false do
      argument :post_id, ID, required: true
    end

    def comment_added(post_id:)
      object if object.post_id.to_s == post_id
    end
  end
end

Triggering Subscriptions

# app/models/post.rb
class Post < ApplicationRecord
  after_create_commit :notify_subscribers

  private

  def notify_subscribers
    MyAppSchema.subscriptions.trigger('postCreated', {}, self)
  end
end

# Or manually in mutations
MyAppSchema.subscriptions.trigger(
  'commentAdded',
  { post_id: comment.post_id },
  comment
)

Authentication & Authorization

Controller Setup

# app/controllers/graphql_controller.rb
class GraphqlController < ApplicationController
  skip_before_action :verify_authenticity_token

  def execute
    result = MyAppSchema.execute(
      params[:query],
      variables: ensure_hash(params[:variables]),
      context: {
        current_user: current_user,
        current_ability: current_ability,
        request: request
      },
      operation_name: params[:operationName]
    )

    render json: result
  rescue StandardError => e
    raise e unless Rails.env.development?
    handle_error_in_development(e)
  end

  private

  def current_user
    return nil unless request.headers['Authorization'].present?

    token = request.headers['Authorization'].split(' ').last
    decoded = JWT.decode(token, Rails.application.credentials.secret_key_base)[0]
    User.find(decoded['user_id'])
  rescue JWT::DecodeError, ActiveRecord::RecordNotFound
    nil
  end

  def ensure_hash(ambiguous_param)
    case ambiguous_param
    when String
      ambiguous_param.present? ? JSON.parse(ambiguous_param) : {}
    when Hash, ActionController::Parameters
      ambiguous_param
    when nil
      {}
    else
      raise ArgumentError, "Unexpected parameter: #{ambiguous_param}"
    end
  end
end

Field-Level Authorization

module Types
  class UserType < Types::BaseObject
    field :email, String, null: false do
      description "User email (only visible to self or admins)"
    end

    def email
      if context[:current_user] == object || context[:current_user]&.admin?
        object.email
      else
        raise GraphQL::ExecutionError, "Not authorized to view email"
      end
    end

    field :private_notes, String, null: true

    def private_notes
      return nil unless context[:current_user] == object
      object.private_notes
    end
  end
end

Query Complexity & Rate Limiting

# app/graphql/my_app_schema.rb
class MyAppSchema < GraphQL::Schema
  mutation(Types::MutationType)
  query(Types::QueryType)
  subscription(Types::SubscriptionType)

  # Limit query complexity
  max_complexity 300
  max_depth 15

  # Validate queries before execution
  validate_max_errors 50

  # Custom complexity analysis
  def self.max_complexity_count_for(query_or_multiplex)
    if query_or_multiplex.context[:current_user]&.admin?
      500  # Higher limit for admins
    else
      300
    end
  end

  # Rate limiting per user
  def self.max_query_count_per_minute_for(query_or_multiplex)
    user = query_or_multiplex.context[:current_user]
    user&.premium? ? 1000 : 100
  end
end

Testing

# spec/graphql/mutations/create_post_spec.rb
RSpec.describe Mutations::CreatePost, type: :graphql do
  let(:user) { create(:user) }
  let(:context) { { current_user: user } }

  let(:mutation) do
    <<~GQL
      mutation($title: String!, $body: String!) {
        createPost(input: { title: $title, body: $body }) {
          post {
            id
            title
            body
          }
          errors
        }
      }
    GQL
  end

  it 'creates a post' do
    variables = { title: "Test Post", body: "Post content" }

    expect {
      result = MyAppSchema.execute(mutation, variables: variables, context: context)
      expect(result.dig('data', 'createPost', 'errors')).to be_empty
    }.to change(Post, :count).by(1)
  end

  it 'returns errors for invalid data' do
    variables = { title: "", body: "" }

    result = MyAppSchema.execute(mutation, variables: variables, context: context)
    errors = result.dig('data', 'createPost', 'errors')

    expect(errors).to be_present
    expect(errors).to include("Title can't be blank")
  end

  it 'requires authentication' do
    result = MyAppSchema.execute(mutation, variables: {}, context: {})
    expect(result['errors']).to be_present
  end
end

Best Practices

✅ Do

  • Use DataLoader to prevent N+1 queries
  • Implement query complexity limits
  • Add field-level authorization
  • Use descriptive field names and descriptions
  • Version your schema with deprecations
  • Test resolvers and mutations
  • Monitor query performance
  • Document your schema

❌ Don't

  • Expose internal database structure directly
  • Allow unlimited query depth/complexity
  • Skip authorization checks
  • Return raw database errors
  • Create overly nested types
  • Forget to handle null cases
  • Expose sensitive data without checks

Remember: GraphQL gives clients flexibility but requires careful attention to performance, security, and schema design. Always use DataLoader and implement proper authorization.

For detailed examples and advanced patterns, see graphql-reference.md.