Rake Tasks

Quail ships two rake tasks for exporting your GraphQL schema. Both are available automatically via the Railtie once the gem is installed.

Prerequisites

Before running either task, ensure your initializer sets schema_class:

config/initializers/quail.rb

Rails.application.config.quail.schema_class = "AppSchema"

If this is missing, the tasks will abort with a helpful error message.

quail:dump

Exports the full GraphQL schema to SDL (Schema Definition Language) format.

bin/rails quail:dump

This produces a schema.graphql file in your project root containing the human-readable type definitions for your entire API:

type Query {
  post(id: ID!): Post
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
  createdAt: ISO8601DateTime!
}

type Mutation {
  createPost(input: CreatePostInput!): Post
  updatePost(input: UpdatePostInput!): Post
  deletePost(input: DeletePostInput!): Post
}

Custom output path

Override the default filename with the SCHEMA_PATH environment variable:

SCHEMA_PATH=tmp/schema.graphql bin/rails quail:dump

How it works

Under the hood, the task calls schema_class.to_definition which triggers Quail’s lazy schema assembly. All registered resources are wired up, and the resulting schema is serialized to SDL via graphql-ruby’s built-in printer.

quail:dump_json

Exports the schema as a JSON introspection result, suitable for tools that consume the standard introspection format.

bin/rails quail:dump_json

This produces a schema.json file containing the full introspection response. The custom path override works the same way:

SCHEMA_PATH=tmp/schema.json bin/rails quail:dump_json

Use cases

Editor tooling

IDEs like VS Code (with the GraphQL extension) and JetBrains IDEs use the SDL file for autocomplete, validation, and inline documentation. Point your editor’s GraphQL config at the dumped file:

{
  "schema": "schema.graphql"
}

CI schema diffing

Commit schema.graphql to version control and diff it in pull requests to catch unintended API changes. Add a CI step that regenerates the file and fails if it differs from what’s checked in:

.github/workflows/schema-check.yml

- name: Check schema is up to date
  run: |
    bin/rails quail:dump
    git diff --exit-code schema.graphql

Client codegen

Tools like Apollo Codegen, graphql-codegen, and Relay Compiler consume the schema to generate typed client code. Run the dump task as a pre-step in your codegen pipeline:

bin/rails quail:dump
npx graphql-codegen --config codegen.yml