graphql

Forge GraphQL: a gqlgen GraphQL server for Go apps on Forge

Forge GraphQL is the GraphQL extension for Forge, the Go backend framework. It runs a gqlgen server inside your app and mounts it on the Forge router, with a GraphQL Playground, query complexity limits, automatic persisted queries, file uploads, Apollo Federation's _service query, Forge metrics and slow query logging. It also ships a small DataLoader package for batching N+1 lookups in Golang resolvers.

Documentation · Quick start · Status · Features · DataLoader · Configuration · FAQ

Quick start

You need Go 1.26 or later. Add Forge and the extension to your module:

go get github.com/xraph/forge@latest
go get github.com/xraph/forge/extensions/graphql@latest

Save this as main.go:

package main

import (
	"log"

	"github.com/xraph/forge"
	"github.com/xraph/forge/extensions/graphql"
)

func main() {
	app := forge.NewApp(forge.AppConfig{
		Name:        "graphql-demo",
		HTTPAddress: ":8080",
		Extensions: []forge.Extension{
			graphql.NewExtension(
				graphql.WithEndpoint("/graphql"),
				graphql.WithPlayground(true),
			),
		},
	})

	if err := app.Run(); err != nil {
		log.Fatal(err)
	}
}

Run it with go mod tidy && go run ., then send a query:

curl -X POST http://localhost:8080/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ hello(name: \"Forge\") version }"}'
# {"data":{"hello":"Hello, Forge!","version":"2.0.0"}}

Open http://localhost:8080/playground in a browser for the GraphQL Playground. The endpoint answers GET as well as POST, so curl -G localhost:8080/graphql --data-urlencode 'query={ version }' works too.

What the extension serves today

Read this before you build on the extension. The server runs the schema that is compiled into this module, schema/schema.graphql, and nothing else:

directive @auth(requires: String) on FIELD_DEFINITION

type Query {
  hello(name: String!): String!
  version: String!
}

type Mutation {
  echo(message: String!): String!
}

There isn't a way to hand it your own schema or resolvers yet. RegisterType, RegisterQuery, RegisterMutation and RegisterSubscription on the GraphQL interface only write a debug log line, Use does nothing, and ExecuteQuery returns an error response telling you to go through HTTPHandler(). The config keys auto_generate_schema and schema_file are accepted and ignored.

So what is it good for today? If you want to see gqlgen running inside a Forge app with the playground, persisted queries, complexity limits and metrics already wired, it shows you how, and the dataloader package is usable on its own in any resolver you write. If you need your own schema right now, run gqlgen in your own module and mount its handler.Server on a Forge route yourself, the same way extension.go does.

Features

The server also registers gqlgen's WebSocket, GET, POST, OPTIONS and multipart transports. The schema has no subscriptions, so the WebSocket transport has nothing to stream yet.

Batch lookups with DataLoader

The dataloader package works on its own, whether or not you use the extension. A Loader collects the keys that concurrent callers ask for during a short wait window, calls your batch function once with all of them, and caches the results:

users := dataloader.NewLoader(dataloader.DefaultLoaderConfig(),
	func(ctx context.Context, keys []any) ([]any, []error) {
		// One query for every key collected in this window.
		values := make([]any, len(keys))
		for i, k := range keys {
			values[i] = fmt.Sprintf("user-%v", k)
		}

		return values, make([]error, len(keys))
	})

user, err := users.Load(ctx, 42)

Order matters. Your batch function has to return a value slice and an error slice that line up with keys, one entry per key, or the wrong caller gets the wrong user. DefaultLoaderConfig() waits 10ms before it dispatches. Prime, Clear and ClearAll manage the cache. One caveat: LoadMany calls Load for one key after another, so it waits a full window per key and doesn't batch. Call Load from concurrent resolvers if you want the batching.

Configuration

The extension reads extensions.graphql from your config, falling back to graphql. Options you pass in code override the file.

extensions:
  graphql:
    endpoint: /graphql
    playground_endpoint: /playground
    enable_playground: true
    max_complexity: 1000
    enable_metrics: true
    enable_logging: true
    log_slow_queries: true
    slow_query_threshold: 1s

These settings change what the server does:

The slow query warning only runs when you have metrics or logging on.

Config has more fields, and some have options, but nothing reads them yet. enable_query_cache (WithQueryCache), max_cache_size and max_upload_size are passed to a second persisted-query cache and a second multipart transport, but gqlgen's default server already registers its own, and those handle every request, so the defaults apply. enable_introspection (WithIntrospection) has no effect because gqlgen's default server always allows introspection, so you can't turn it off from config today. max_depth (WithMaxDepth), query_timeout (WithTimeout), enable_dataloader (WithDataLoader), dataloader_batch_size, dataloader_wait, query_cache_ttl, enable_cors and allowed_origins (WithCORS), enable_tracing (WithTracing), auto_generate_schema and schema_file are validated where there's a rule (max_depth has to be at least 1, query_timeout positive) and otherwise left alone.

WithConfig replaces the whole config, and WithRequireConfig(true) makes a missing config section an error at startup. In the container you'll find *graphql.GraphQLService and the graphql.GraphQL interface, both backed by one instance.

Documentation

FAQ

How do I add a GraphQL endpoint to a Go app built on Forge?

Add graphql.NewExtension() to your app's Extensions. You get /graphql and /playground on the Forge router. Read what the extension serves today first, because the schema is fixed for now.

Can I use my own GraphQL schema with Forge GraphQL?

Not through the extension yet. The registration methods are placeholders. Generate your schema with gqlgen in your own module and register its handler on a Forge route.

Does it support Apollo Federation?

The generated code includes Federation v2, and { _service { sdl } } returns the module's schema. Entity resolvers aren't there, because the built-in schema has no entities.

How do I fix the N+1 problem in Go GraphQL resolvers?

Use the dataloader package: create one Loader per request and call Load from each resolver, so lookups that happen together turn into one batch call.

Contributing

The extension is its own Go module inside the Forge repository. Its go.mod has no replace for the Forge root, so it builds against the published Forge version its require line names, even inside this repository. Test it from its directory:

cd extensions/graphql
GOWORK=off go test -race ./...
GOWORK=off golangci-lint run ./...

After you edit schema/schema.graphql, regenerate the code with go run github.com/99designs/gqlgen generate from the same directory. AGENTS.md has the full build, lint and release rules for the repository, and CONTRIBUTING.md has the contribution guidelines.

License

Forge GraphQL is part of Forge and is available under the Apache License 2.0.