Migrate to grx

This section walks through migrating an existing Go GraphQL service to grx. Pick the guide that matches the library you're leaving:

Both guides assume you're already comfortable with the source library and skip GraphQL fundamentals. They focus on the delta - what disappears, what shows up new, and how to keep your existing schema shape intact while you switch executors.

What you gainCopy Anchor Link

• Performance. The benchmark/ module compares Executor.Execute to graphql-go and graph-gophers on realistic operations; profile your workload for decisive numbers.
• Zero runtime dependencies. grx is a single Go module that imports only the standard library. The whole runtime is auditable, vendorable, and easy to upgrade.
• First-class subscriptions. WebSocket (graphql-transport-ws) and Server-Sent Events transports ship in the box. See Realtime subscriptions.
• Plugin lifecycle hooks for logging, tracing, auth, and request-id propagation without reaching into the executor. See Write a Custom Plugin.

What's missing todayCopy Anchor Link

grx does not yet implement the full October 2021 spec. Before committing to a migration, compare your existing schema with the current grx feature set. The most likely blockers today are:

• Enum, interface, and union types may require explicit registration in schema.Config.
• Custom scalars can't be registered yet - only the built-in String, Int, Float, Boolean, ID scalars are available.
• Field aliases, fragments, and @skip / @include should be checked against the current executor behavior before migration.
• Default argument values and descriptions / deprecation metadata aren't carried through.

If your schema uses any of those, file an issue so the priority is visible - or stay on your current library until the relevant checklist items are complete.

Recommended orderCopy Anchor Link

For both source libraries, the lowest-risk migration order is:

1. Read the Define your schema and Resolvers concept pages to internalise grx's struct-tag conventions.
2. Stand up a parallel grx server in a sibling package that defines the same schema using the patterns from the migration guide. Don't delete anything yet.
3. Run both executors against the same fixture to confirm responses match field-for-field. Steal TestImplementationsAgree from benchmark/bench_test.go as a template.
4. Switch your HTTP handler to grx.NewServer and remove the old library from your go.mod.
5. Move plugins last. RequestStart is the hook you want for anything that used to live in middleware around graphql.Do or the graph-gophers HTTP wrapper.