Guide · Open source
How to use gqlgen: set up a Go GraphQL server from a schema
Updated · written with AI from the project's own documentation and checked against our catalogue data
gqlgen is a Go library for building GraphQL servers. You write your API in the GraphQL Schema Definition Language, and gqlgen generates Go code for the types and resolver functions, so most of your work is the logic that fetches data. This guide is for Go developers who want type-safe code and walks through the quick start, how to control nested field fetching, and the main configuration options shown in the project README.
gqlgen99designs/gqlgen · ★ 10.8k · MIT Install options & downloads Quick start
- 1Create a Go module. Make a project folder and run go mod init in it so the project has a module.
- 2Add gqlgen as a tool. Run go get -tool github.com/99designs/gqlgen to add the library as a tool dependency.
- 3Initialise gqlgen. Run go tool gqlgen init to create the config and generate the models and resolver code.
- 4Write your resolvers. Fill in the generated resolver functions with the logic that fetches your data.
- 5Start the server. Run go run server.go to start the GraphQL server.
- 6Tune nested fields. If nested fields should only be fetched on request, use a custom model or an explicit resolver in gqlgen.yml.
What does gqlgen do?
gqlgen follows a schema-first approach: you define the API with the GraphQL Schema Definition Language, and the library generates the code from it. The project emphasises type safety, so the generated code avoids map[string]interface{}, and it generates the repetitive parts so you can focus on the app itself.
It is written for Go and the README examples are all Go code. If you need a GraphQL server in another language, gqlgen is not the right tool.
Install gqlgen and create a project
The quick start uses Go modules. Create a project folder, initialise a module, then add gqlgen as a tool dependency. Install requires Go; the README excerpt does not state a minimum Go version, so check the getting started guide for that.
Then initialise the gqlgen config and generate the models.
mkdir example
cd example
go mod init example
go get -tool github.com/99designs/gqlgen
go tool gqlgen initRun the server
After generation, start the server with the command from the quick start. The README's quick start refers to a server.go file, which the generated project provides.
go run server.goControl which nested fields are fetched
With nested or recursive schemas, such as a User type with a friends list, you may not want to fetch friends unless the client asks for it. gqlgen offers two approaches: a custom model that leaves out the field, or an explicit resolver that gqlgen generates for that field.
With a custom model, you write a Go struct without the field and point gqlgen at it in gqlgen.yml. With an explicit resolver, you keep the generated model and set resolver: true on the field. Either way, you then implement the resolver function, which runs only when the field is requested.
Field resolvers run concurrently in separate goroutines. You can adjust the degree of concurrency with the worker_limit configuration attribute.
- Custom model: reference your struct under models in gqlgen.yml.
- Explicit resolver: set resolver: true for the field under models, then run generate.
- Inline alternative: use the @goModel and @goField directives in the schema.
models:
User:
fields:
friends:
resolver: true # force a resolver to be generatedChange the ID type
By default the GraphQL ID type maps to a Go string. You can remap it in config to an integer or unsigned integer. The first type in the list is the default, and it is always used when generating models from the schema and for resolver arguments.
- Available options in the README: graphql.IntID, graphql.ID and graphql.UintID.
- gqlgen can bind to strings or ints for models you wrote yourself, but the default type is always the first entry in the list.
models:
ID:
model:
- github.com/99designs/gqlgen/graphql.IntID
- github.com/99designs/gqlgen/graphql.ID
- github.com/99designs/gqlgen/graphql.UintIDTurn off interface getters
Interfaces get getter methods so common fields can be read without casting to a concrete type. These were added in v0.17.14. Relay-style Connections cannot be built with simple getters, so if you do not want them, set omit_getters in gqlgen.yml.
omit_getters: trueWhat people use it for
- Building a new GraphQL API in Go where the schema is written first.
- Keeping typed Go models instead of loosely typed maps for GraphQL data.
- Fetching nested fields such as a user's friends only when a client requests them.
- Using a generated server skeleton as a starting point for your own resolver logic.
Frequently asked questions
Is gqlgen free to use?
gqlgen is released under the MIT licence, as stated in the project information. Check the licence file in the repository for the full terms.
What do I need to install gqlgen?
You need Go and a Go module for your project. The README excerpt does not specify a Go version, so check the getting started guide on gqlgen.com before you install.
How do I install gqlgen?
Create a module with go mod init, then run go get -tool github.com/99designs/gqlgen. After that, run go tool gqlgen init to generate the config and models.
How do I stop gqlgen fetching nested fields I do not need?
Use a custom model that omits the field, or set resolver: true on the field in gqlgen.yml so gqlgen generates a resolver for it. The resolver only runs when the field is requested.
Can I use gqlgen with a language other than Go?
No. gqlgen is a Go library, and the README shows only Go code. For other languages you would need a different GraphQL server library.
How does gqlgen compare with graphql-go or graph-gophers/graphql-go?
The source names graphql-go, gql (graphql-go/graphql) and graph-gophers/graphql-go as comparable Go projects, and links a feature comparison on gqlgen.com. The README does not benchmark them, so compare them against your own requirements.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
gqlgen suits Go developers starting a new GraphQL API who want to write the schema first and get typed code generated from it. It is not a finished application, so you still write the resolver logic, and it is a poor fit for teams working in other languages.
Install options & downloads