BaseQL is a Go framework for rapidly building powerful graphql servers. BaseQL has support for schemas automatically generated from Go types, live queries, query batching, and more. BaseQL is an open-source project from {basecode}. Its a fork of the original thunder.
BaseQL has a number of features to make it easy to build sophisticated schemas. This section provides a brief overview of some of them.
BaseQL generates resolvers automatically from Go struct types and function
definitions. For example, the Friend
struct below gets exposed as a graphql
object type with firstName
and lastName
resolvers that return the fields
on the type.
// Friend is a small struct representing a person.
type Friend struct {
FirstName string
Last string `graphql:"lastName"` // use a custom name
Added time.Date `graphql:"-"` // don't expose over graphql
}
// FullName builds a friend's full name.
func (f *Friend) FullName() string {
return fmt.Sprintf("%s %s", f.FirstName, f.Last)
}
// registerFriend registers custom resolvers on the Friend type.
//
// Note: registerFriend wouldn't be necessary if the type only
// had the default struct field resolvers above.
func registerFriend(schema *schemabuilder.Schema) {
object := schema.Object("Friend", Friend{})
// fullName is a computed field on the Friend{} object.
object.FieldFunc("fullName", Friend.FullName)
}
BaseQL has support for automatically updating queries using resolver invalidation. With invalidation, code on the server can trigger updates on the client using a persistent WebSocket connection.
The simplest example is a clock that updates over time. Every 10 seconds the
time
function will be recomputed, and the latest time will be sent to the
client.
// registerQuery registers the resolvers on the core graphql query type.
func registerQuery(schema *schemabuilder.Schema) {
query := schema.Query()
// time returns the current time.
query.FieldFunc("time", func(ctx context.Context) string {
// Invalidate the result of this resolver after 10 seconds.
reactive.InvalidateAfter(ctx, 10 * time.Second)
// Return the current time. Will be re-executed automatically.
return time.Now().String()
})
}
Using BaseQL's lightweight sqlgen
and livesql
ORM, it's easy to write
automatically updating MySQL queries. The example below returns a live-updating
lists of posts from a database table. Whenever somebody INSERT
s or UPDATE
s
a row in the table, the resolver is re-executed and the latest lists of posts
is sent to the client. Behind the scenes, the livesql
package uses MySQL's
binary replication log to detect changes to the underlying data.
// A Post holds a row from the MySQL posts table.
type Post struct {
Id int64 `sqlgen:",primary"`
Title string
}
// Server implements a graphql server. It has persistent handles to eg. the
// database.
type Server struct {
db *livesql.LiveDB
}
// registerQuery registers the root query resolvers.
func (s *Server) registerQuery(schema *schemabuilder.Schema) {
query := schema.Query()
// posts returns all posts in the database.
query.FieldFunc("posts", func(ctx context.Context) ([]*Post, error) {
var posts []*Post
if err := s.db.Query(ctx, &posts, nil, nil); err != nil {
return nil, err
}
return posts, nil
})
}
BaseQL automatically runs independent resolvers in different goroutines to
quickly compute complex queries. To keep large queries efficient, BaseQL has
support for built-in batching similar to Facebook's dataloader
. With
batching, BaseQL automatically combines many parallel individual calls to a
batch.Func
's Invoke
function into a single call to Many
function.
Batching is very useful when fetching related objects from a SQL database. BaseQL's
sqlgen
and livesql
have built-in support for batching and will combine SELECT WHERE
statements using an IN
clause. For example, the program below will fetch all posts and
their authors in just two queries.
type Post struct {
Id int64 `sqlgen:",primary"`
Title string
AuthorId int64
}
// An Author represents a row in the authors table.
type Author struct {
Id int64 `sqlgen:",primary"`
Name string
}
// registerPost registers resolvers on the Post type.
func (s *Server) registerPost(schema *schemabuilder.Schema) {
object := schema.Object("post", Post{})
// author return the Author object corresponding to a Post's AuthorId.
object.FieldFunc("author", func(ctx context.Context, p *Post) (*Author, error) {
var author *Author
if err := s.db.QueryRow(ctx, &author, sqlgen.Filter{"id": p.AuthorId}, nil); err != nil {
return nil, err
}
return author, nil
})
}
To execute the query
query PostsWithAuthors {
posts {
title
author {
name
}
}
}
BaseQL will execute SELECT * FROM posts
and, if that returns three posts
with author IDs 10
, 20
, and 31
, a follow-up query SELECT * FROM authors WHERE id IN (10, 20, 31)
.
To get started quickly without wrangling any JavaScript, BaseQL comes with
a built-in graphiql
client as an HTTP handler. To use it, simply expose
with Go's built-in HTTP server.
// Expose schema and graphiql.
http.Handle("/graphql", graphql.Handler(schema))
http.Handle("/graphiql/", http.StripPrefix("/graphiql/", graphiql.Handler()))
http.ListenAndServe(":3030", nil)
A large GraphQL server might have many resolvers on some shared types. To
keep packages reasonably-sized, BaseQL's schema builder supports extending a
schema. For example, if you have a User
type with a resolver photos
implemented by your photos
package, and resolver events
implemented by
your calendar
package, those packages can independently register their
resolvers:
package common
type User struct {}
package photos
type PhotosServer {}
func (s *PhotosServer) registerUser(schema *schemabuilder.Schema) {
object := schema.Object("User", common.User{})
object.FieldFunc("photos", s.fetchUserPhotos)
}
package events
type EventsServer {}
func (s *EventsServer) registerUser(schema *schemabuilder.Schema) {
object := schema.Object("User", common.User{})
object.FieldFunc("events", s.fetchUserEvents)
}
First, a fair warning. The BaseQL library is still a little bit tricky to use outside of {basecode}. The examples above and below work, but eg. the
npm
client still requires some wrangling.
The program below is a fully-functional graphql server written using BaseQL. It
does not use sqlgen
, livesql
, or batching, but does include a live-updating
resolver.
package main
import (
"context"
"net/http"
"time"
"github.com/base-go/baseql/graphql"
"github.com/base-go/baseql/graphql/graphiql"
"github.com/base-go/baseql/graphql/introspection"
"github.com/base-go/baseql/graphql/schemabuilder"
"github.com/base-go/baseql/reactive"
)
type post struct {
Title string
Body string
CreatedAt time.Time
}
// server is our graphql server.
type server struct {
posts []post
}
// registerQuery registers the root query type.
func (s *server) registerQuery(schema *schemabuilder.Schema) {
obj := schema.Query()
obj.FieldFunc("posts", func() []post {
return s.posts
})
}
// registerMutation registers the root mutation type.
func (s *server) registerMutation(schema *schemabuilder.Schema) {
obj := schema.Mutation()
obj.FieldFunc("echo", func(args struct{ Message string }) string {
return args.Message
})
}
// registerPost registers the post type.
func (s *server) registerPost(schema *schemabuilder.Schema) {
obj := schema.Object("Post", post{})
obj.FieldFunc("age", func(ctx context.Context, p *post) string {
reactive.InvalidateAfter(ctx, 5*time.Second)
return time.Since(p.CreatedAt).String()
})
}
// schema builds the graphql schema.
func (s *server) schema() *graphql.Schema {
builder := schemabuilder.NewSchema()
s.registerQuery(builder)
s.registerMutation(builder)
s.registerPost(builder)
return builder.MustBuild()
}
func main() {
// Instantiate a server, build a server, and serve the schema on port 3030.
server := &server{
posts: []post{
{Title: "first post!", Body: "I was here first!", CreatedAt: time.Now()},
{Title: "graphql", Body: "did you hear about BaseQL?", CreatedAt: time.Now()},
},
}
schema := server.schema()
introspection.AddIntrospectionToSchema(schema)
// Expose schema and graphiql.
http.Handle("/graphql", graphql.Handler(schema))
http.Handle("/graphiql/", http.StripPrefix("/graphiql/", graphiql.Handler()))
http.ListenAndServe(":3030", nil)
}
For use with non-live clients (e.g. Relay, Apollo) baseql provides an HTTP handler that can serve POST requests, instead of having the client connect over a websocket. In this mode, baseql does not provide live query updates.
In the above example, the main
function would be changed to look like:
func main() {
// Instantiate a server, build a server, and serve the schema on port 3030.
server := &server{
posts: []post{
{Title: "first post!", Body: "I was here first!", CreatedAt: time.Now()},
{Title: "graphql", Body: "did you hear about BaseQL?", CreatedAt: time.Now()},
},
}
schema := server.schema()
introspection.AddIntrospectionToSchema(schema)
// Expose GraphQL POST endpoint.
http.Handle("/graphql", graphql.HTTPHandler(schema))
http.ListenAndServe(":3030", nil)
}
BaseQL can emit a GraphQL introspection query schema useful for compatibility with other GraphQL tooling. Alongside code from the above example, here is a small program for registering our schema and writing the JSON output to stdout.
// schema_generator.go
func main() {
// Instantiate a server and run the introspection query on it.
server := &server{...}
builderSchema := schemabuilder.NewSchema()
server.registerQuery(builderSchema)
server.registerMutation(builderSchema)
// ...
valueJSON, err := introspection.ComputeSchemaJSON(*builderSchema)
if err != nil {
panic(err)
}
fmt.Print(string(valueJSON))
}
This program can then be run to generate schema.json
:
$ go run schema_generator.go > schema.json
The source code in this repository is organized as follows:
- The example/ directory contains a basic BaseQL application.
- The graphql/ directory contains BaseQL's graphql parser and executor.
- The reactive/ directory contains BaseQL's core dependency-tracking and live-update mechanism.
- The batch/ directory contains BaseQL's batching package.
- The diff/ and merge/ directories contain BaseQL's JSON diffing library used for live queries.
- The livesql/ directory contains a BaseQL driver for MySQL.
- The sqlgen/ directory contains a lightweight SQL query generator used by livesql/.
BaseQL has proven itself in production use at {basecode} for close to two years. This repository is still under development, and there will be some breaking changes to the API but they should be manageable. If you're adventurous, please give it a try.