rails-graphql-patterns

Rails GraphQL Patterns

Analyze and recommend patterns for building GraphQL APIs in Rails with graphql-ruby.

Follow standard graphql-ruby conventions for type definitions, input types, enum types, query types, and basic mutations. This skill focuses on non-obvious patterns and opinionated decisions.

Core Principles

1. Batch loading: Always use DataLoader to prevent N+1 queries — never resolve associations directly
2. Structured errors: Return error arrays in mutation payloads, not exceptions
3. Field-level authorization: Check permissions per field, not just per query
4. Complexity limits: Set max_complexity and max_depth on the schema
5. Null annotations: Be intentional with null: true/false on every field

DataLoader for N+1 Prevention

Every association field MUST use DataLoader. Never call object.association directly in a resolver.

class Sources::RecordLoader < GraphQL::Dataloader::Source
  def initialize(model_class, column: :id)
    @model_class = model_class
    @column = column
  end

  def fetch(ids)
    records = @model_class.where(@column => ids).index_by { |r| r.send(@column) }
    ids.map { |id| records[id] }
  end
end

# Usage in type
def author
  dataloader.with(Sources::RecordLoader, User).load(object.user_id)
end

See patterns.md for AssociationLoader and CountLoader variants.

Connection Types (Pagination)

Always use connection types for list fields — never return unbounded arrays.

module Types
  class PostConnectionType < GraphQL::Types::Connection
    edge_type(Types::PostEdgeType)
    field :total_count, Integer, null: false

    def total_count
      object.items.size
    end
  end
end

# In query type
field :posts, Types::PostConnectionType, null: false, connection: true do
  argument :filter, Types::PostFilterInput, required: false
end

Subscriptions — Triggering from Models

# Trigger from model after_create_commit, not from mutations
class Post < ApplicationRecord
  after_create_commit :notify_subscribers

  private

  def notify_subscribers
    MyAppSchema.subscriptions.trigger(:post_created, {}, self)
  end
end