GQ - A library to build GraphQL servers

(Mike Poindexter) #1

GQ is a new library to build GraphQL servers in Go.

When HouseCanary set out to build a GraphQL server to act as an API gateway to a number of existing services, we found that none of the existing libraries had quite the functionality we wanted. The biggest challenge was in scheduling batched calls to other services. All existing projects seemed to support only time based batching. We wanted to we able to deterministically schedule calls at convenient points in the query execution, similar to what one would do in Node by scheduling batch calls at the next event loop tick. In addition, each of the existing libraries seemed to fall short in some aspect of the developer experience. We researched the following libraries before creating this project:


Schema first approach. You write a schema, and then bind types to the schema in a config file, then use the schema and config file to generate code.

Weakness - need to keep definitions in schema and structs in sync, requires code generation.


Schema first approach. You write a schema, and then provide a root type to bind to the schema. Methods are bound to the schema.

Weakness - you have to write a method for each field, leading to lots of boilerplate for large DTOs.


Schema in code. You build up the schema by constructing it in Go objects.

Weakness - very verbose/boilerplate heavy, not type checked.


Schema built from structs, with separate method registration.

Weakness - verbose registration of resolver methods. Limited flexibility in schema definition.

After researching each of these options, we set out to build a struct-first development experience that needed minimal boiler plate code, leveraged the power of GraphQL schema definitions, and allowed for efficient query batching. You can see the results of our work at for documentation and examples of how the library diverges from existing GraphQL libraries for Go.

At HouseCanary we are using this library as the foundation to a major internal service. We expect to continue to improve and maintain this library.