Prerequisites

System Requirements

Before installing Quail, make sure your environment meets these requirements:

• Ruby >= 3.2.0
• Rails >= 7.0
• A working Rails application with ActiveRecord models
• The graphql gem (>= 2.0) — installed automatically as a Quail dependency

If you already have a Rails app with models defined, you’re ready to go.

What is GraphQL?

If you’ve never worked with GraphQL before, don’t worry — the concepts map directly to things you already know from Rails.

Instead of defining multiple REST endpoints (/articles, /articles/:id, /articles/:id/comments), GraphQL exposes a single endpoint where the client specifies exactly what data it needs. Think of it as letting the client write its own SELECT statement, but safely constrained by a schema you define.

Key Concepts (in Rails Terms)

GraphQL Concept	Rails Analogy
Schema	Like routes.rb — defines what’s available
Types	Like serializers or presenters — define the shape of data
Queries	Like GET controller actions — read data
Mutations	Like POST, PATCH, DELETE actions — write data
Subscriptions	Like ActionCable channels — push real-time updates

A Simple Example

Here’s a GraphQL query that fetches an article with its author name:

query {
  article(id: "1") {
    title
    body
    author {
      name
    }
  }
}

The response comes back as JSON matching the shape you asked for:

{
  "data": {
    "article": {
      "title": "Getting Started with Quail",
      "body": "Quail makes GraphQL feel like Rails...",
      "author": {
        "name": "Taylor"
      }
    }
  }
}

No over-fetching, no under-fetching — the client gets exactly what it requested.

For a deeper dive into GraphQL fundamentals, the official GraphQL introduction is an excellent resource.

How Quail Fits In

Quail sits between your Rails models and graphql-ruby. You define resource classes with a simple DSL, and Quail generates the GraphQL types, queries, mutations, and subscriptions for you.

You don’t need to be a GraphQL expert to use Quail. The DSL abstracts away the complexity of graphql-ruby’s class hierarchy — you declare what you want exposed, and Quail handles the wiring. For advanced use cases (custom resolvers, complex authorization), understanding GraphQL fundamentals helps, but it’s not required to get started.

If you know how to define a Rails model and write a serializer, you already have the mental model you need.