Open-source project
graph-gophers/graphql-go avatar
graph-gophers/graphql-go

graph-gophers/graphql-go: a schema-first GraphQL server for Go built on method sets

GraphQL server with a focus on ease of use

4,752 stars502 forksGoBSD-2-Clause

At a glance

What is it?
graphql-go parses SDL at startup and matches it to Go resolvers by method name, which keeps the API small but pushes schema and code apart. A look at the mechanism, the install path, the schema options, and where gqlgen differs.
Who is it for?
Adopt graph-gophers/graphql-go when your team already writes SDL by hand and wants resolvers that are ordinary Go methods, with no code generation step in the build. Do not adopt it if you need generated types, a plugin ecosystem, or compile-time guarantees that every schema field has a resolver.
Can I use it commercially?
Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • graph-gophers/graphql-go4,752 ★ · -7
Star history
Repository2026-09-232026-11-15
graph-gophers/graphql-go4.8k4.8k

-7 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem graphql-go solves: SDL stays the source of truth, resolvers stay plain Go

Most Go GraphQL servers are code-first. You describe types in Go, a generator emits the schema, and the schema is an artifact you rarely read. graph-gophers/graphql-go inverts that. The README states the project goal directly: full support of the September 2025 GraphQL specification with idiomatic, easy to use Go packages. The schema is a string you write yourself, and the library parses it at startup.

The audience is narrow but real. It suits teams that already keep .graphql files in review, that want the schema diff visible in a pull request rather than buried in generated output, and that are willing to accept a looser coupling between schema and code in exchange for skipping a build step. It is a poor fit for anyone who expects the compiler to tell them a resolver is missing.

That last point is the trade-off the project makes deliberately. Resolvers are matched to the schema by method sets, so a field with no matching method is a runtime problem, not a build failure. The README lists schema type-checking against resolvers as a feature, and it is, but the check happens when MustParseSchema runs, which means a server that fails to start rather than a build that fails to compile.

How resolvers bind to the schema: method sets, case-insensitive names, and the Query/Mutation split

The binding rule is the whole architecture. A resolver must have one method or field for each field of the GraphQL type it resolves. The method name has to be exported and match the schema field name in a non-case-sensitive way. So a schema field named hello can be served by a method named Hello, and a field named helloWorld by HelloWorld.

A resolver method takes up to two arguments and returns up to two results. The optional first argument is context.Context. The mandatory second argument, present only when the GraphQL field has arguments, is a pointer to an anonymous struct whose exported fields match the GraphQL argument names, again case-insensitively. The results are the field value and an optional error.

The README shows both signatures:

go
func (r *helloWorldResolver) Hello() string {
    return "Hello world!"
}

and

go
func (r *helloWorldResolver) Hello(ctx context.Context) (string, error) {
    return "Hello world!", nil
}

Struct fields can also serve as resolvers, but only when UseFieldResolvers() is passed as a schema option, and even then a struct field is used only if there is no method for it, it does not implement an interface method, and it has no arguments. That precedence order matters: adding a method silently shadows a field.

The Query, Mutation and Subscription methods on the root resolver exist because the specification allows the same field name in different operation types. Without them, a schema with hello on both Query and Mutation would collide in a single root struct. The README dates this feature to v1.6.0 and shows a RootResolver whose Query() and Mutation() methods return separate resolver structs.

Installing graphql-go and running a first query

The README's getting started section is a single main.go. It imports the root package and the relay subpackage, which supplies the HTTP handler. The module path is github.com/graph-gophers/graphql-go, and go.mod declares go 1.25.0, so a toolchain at or above that version is required.

go
package main

import (
    "log"
    "net/http"

    graphql "github.com/graph-gophers/graphql-go"
    "github.com/graph-gophers/graphql-go/relay"
)

type query struct{}

func (query) Hello() string { return "Hello, world!" }

The schema is a raw string literal passed to graphql.MustParseSchema together with the resolver. The relay.Handler wraps the parsed schema and is mounted on a path, which the README sets to /query. The server listens on :8080.

go
func main() {
    s := `
        type Query {
                hello: String!
        }
    `
    schema := graphql.MustParseSchema(s, &query{})
    http.Handle("/query", &relay.Handler{Schema: schema})
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Run it with go run main.go. The README then gives the verification command, a POST with a JSON body containing the query field:

bash
curl -XPOST -d '{"query": "{ hello }"}' localhost:8080/query

The response should carry the string from the Hello method. MustParseSchema panics on a bad schema, which is convenient in main and wrong inside a request path. For anything beyond a demo, the README points to the examples section of the project wiki, and the repository ships example directories including caching, enum, federation, prefetch, social and starwars.

Schema options are where the operational limits live

The options list is short and each entry maps to a concrete failure mode. MaxDepth(n int) caps field nesting depth and defaults to 0, which disables the check entirely. MaxQueryLength(n int) caps query bytes and also defaults to 0. The README is explicit that setting MaxQueryLength is highly recommended when accepting queries from untrusted clients, and the same reasoning applies to MaxDepth: without them, a deeply nested or oversized query reaches the executor.

MaxParallelism(n int) caps how many resolvers per request run in parallel and defaults to 10. Because the README lists parallel execution of resolvers as a feature, this default is doing real work: a wide query fans out to at most ten concurrent resolvers unless you raise it. Raising it without knowing what your database tolerates is the obvious way to turn a fast query into a connection-pool incident.

DisableIntrospection() turns off introspection queries. DisableMemoryPooling() turns off the internal execution-path memory pooling that is enabled by default, and MaxPooledBufferCap(n int) sets the largest buffer kept in that pool, defaulting to 16KB, with larger buffers discarded rather than pooled. These two are tuning knobs, not correctness knobs, and the README says DisableMemoryPooling() is intended for diagnostics and benchmark comparisons.

UseStringDescriptions() changes how descriptions are read: when it is off, schema comments are parsed as descriptions; when on, double and triple quoted strings are. Picking the wrong one silently changes your introspection output rather than failing. Tracer, Logger and PanicHandler default to noop.Tracer, exec.DefaultLogger and errors.DefaultPanicHandler respectively.

Panic handling, prefetch and the N+1 question

The README lists handling panics in resolvers as a feature, and the PanicHandler option transforms panics into errors during query execution. The default is errors.DefaultPanicHandler. This is a meaningful design choice: a panicking resolver does not take down the request handler, but it also does not surface as a crash you would notice in a stack trace unless your logger is wired up. The Logger option, defaulting to exec.DefaultLogger, is what records those panics.

On the N+1 problem, the README says the library can inspect the selected fields and their args to prefetch data. It does not claim to solve N+1 automatically. There is a DisableFieldSelections() option that turns off capturing child field selections used by the helper APIs, and the repository includes example/prefetch and example/caching directories. The practical reading is that field selection capture gives you the information to batch, and batching is still your code. The repository also carries selection.go plus the selection_test.go and selection_args_test.go test files, which is where that machinery lives.

Subscriptions are supported, with the README pointing to a separate repository, graph-gophers/graphql-transport-ws, for a sample WebSocket transport. That means the transport is not in this module. If your deployment expects subscriptions to work out of the box, the extra dependency and its maintenance are yours to assess.

Where graphql-go is the wrong tool

The strongest argument against it is the absence of code generation. Nothing in the repository layout suggests a generator, and the README describes resolvers matched by method sets, which is a runtime binding. In a schema with hundreds of fields, a renamed field or a typo in a method name is caught when the schema is parsed, not when the package is compiled. Whether that is acceptable depends on how much of your schema changes per release and how early your startup check runs.

Memory pooling being on by default is a second consideration. It is an optimization most users will never think about, and The README says DisableMemoryPooling() is intended for diagnostics and benchmark comparisons.

The description strings behavior is a third. UseStringDescriptions() changes parsing semantics globally for the schema. A team that migrates an existing schema with comment-based descriptions and turns the option on will get different introspection output.

Finally, the project targets the September 2025 specification. If you depend on draft features beyond that specification, the README makes no promise about them.

graphql-go compared with gqlgen: runtime binding versus generated code

The comparison people actually search for is gqlgen versus graphql-go, and the difference is structural rather than a matter of taste. gqlgen is generator-based: you write a schema, run a generator, and it produces Go types and resolver interfaces that the compiler enforces. graph-gophers/graphql-go does no generation. You write the schema string, pass it to MustParseSchema with a resolver struct, and the match happens by method name at parse time.

That single difference cascades. With generated code, adding a field to the schema and forgetting the resolver is a compile error. With graphql-go, it is a startup panic from MustParseSchema, assuming you call it during initialization. With generated code, you get typed models for inputs and outputs. With graphql-go, GraphQL arguments arrive as a pointer to an anonymous struct you declare yourself, and the field names must match the argument names case-insensitively.

The trade in the other direction is build complexity. graphql-go has three direct dependencies in go.mod: opentracing-go, and the OpenTelemetry otel and otel/trace modules. There is no generator in the build, no generated files to review, and no regeneration step when the schema changes. For a small service with a stable schema, that is a smaller surface. For a large schema with many contributors, the missing compile-time check is a recurring cost that gqlgen does not charge.

A middle position exists: use graphql-go while the schema is small and the team is small, and treat the schema-size threshold as the trigger to re-evaluate. The repository's example/federation directory suggests the project is used in composed graphs.

Maintenance, licence and the cost of upgrading

The repository is not archived. The last push was on 2026-11-01, and the most recent release, v1.11.0, is dated 2026-11-02. The two before it, v1.10.3 and v1.10.2, landed on 2026-09-22 and 2026-05-20. The cadence is uneven: a gap from May to September, then another release in November. Nothing in the repository layout suggests a deprecation notice, and CHANGELOG.md is present at the top level.

The licence is BSD-2-Clause, which is permissive and short. It is a two-clause BSD licence rather than the three-clause form, so there is no endorsement clause. That makes it compatible with commercial use and with redistribution in a larger product, subject to retaining the copyright notice and the licence text. This is a description of the licence identifier, not legal advice; the LICENSE file and your own counsel are the authority.

Upgrade cost is mostly driven by the Go version floor. go.mod declares go 1.25.0, so any service below that toolchain cannot consume the current module without a toolchain bump. The dependency set is small and stable-looking: opentracing-go v1.2.0 and the OpenTelemetry otel and otel/trace modules at v1.43.0. Note that both tracing standards are supported, which means a project migrating from OpenTracing to OpenTelemetry has both available.

The CHANGELOG.md file at the repository root is the place to check before upgrading across minor versions, particularly for changes to the schema options list, since those change runtime behavior rather than types.

Editorial conclusion

Adopt graph-gophers/graphql-go when your team already writes SDL by hand and wants resolvers that are ordinary Go methods, with no code generation step in the build. Do not adopt it if you need generated types, a plugin ecosystem, or compile-time guarantees that every schema field has a resolver. Before committing, verify three things: that the September 2025 specification support covers the directives you use, that MaxDepth and MaxQueryLength are actually set on your schema options, and that MaxParallelism matches what your data layer can absorb.

Frequently asked questions

What is graph-gophers/graphql-go?

It is a GraphQL server library for Go whose stated goal is full support of the September 2025 GraphQL specification with idiomatic, easy to use packages. You supply the schema as a string and a resolver struct, and the library matches schema fields to resolver methods by name.

How do I install and run graph-gophers/graphql-go?

Add the module github.com/graph-gophers/graphql-go to a Go project on toolchain 1.25.0 or above. The README's getting started example calls graphql.MustParseSchema with a schema string and a resolver, mounts a relay.Handler on a path, and serves it with net/http; go run main.go starts it.

How do I write a resolver for graph-gophers/graphql-go?

A resolver needs one exported method or field per schema field, with a name matching the field case-insensitively. The method may take a context.Context and, when the field has arguments, a pointer to a struct whose exported fields match the argument names. It returns the value and optionally an error.

How is graph-gophers/graphql-go different from gqlgen?

graphql-go binds resolvers to the schema at parse time by method set, with no code generation step. gqlgen generates Go types and resolver interfaces from the schema, so a missing resolver is a compile error rather than a startup panic.

Does graph-gophers/graphql-go support subscriptions?

Yes. The README lists subscriptions as a feature and points to a separate repository, graph-gophers/graphql-transport-ws, for a sample WebSocket transport, so the transport itself is not part of this module.

How do I limit query depth or length in graph-gophers/graphql-go?

Pass MaxDepth(n int) and MaxQueryLength(n int) as schema options. Both default to 0, which disables the check, and the README says setting MaxQueryLength is highly recommended when accepting queries from untrusted clients.

Official sources

  1. graph-gophers/graphql-go on GitHub
  2. Issues
  3. License: BSD-2-Clause
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/graph-gophers-graphql-go.svg)](https://hysenlabs.com/projects/graph-gophers-graphql-go)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/graph-gophers-graphql-go.svg)](https://hysenlabs.com/projects/graph-gophers-graphql-go)

Was this useful?