Custom Business Logic via Go

Introduction

The Go Connector can be added to any project to incorporate custom business logic directly into your supergraph.

This can be used to enrich data returned to clients, or to write custom mutations in Go.

Prerequisites

If you've never used Hasura DDN, we recommend that you first go through the getting started. 😊

Functions or Procedures

Go functions exported from a file in the connector will then be available from your Hasura DDN GraphQL API in the form of either functions or procedures.

In Hasura metadata, functions are used for read operations. They will not modify the data in the database and can only be used to retrieve data.

Conversely, procedures are used for write operations. They can modify the data in the database and can be used to create, update, or delete data.

The distinction is important in metadata because it allows the system to know what types to expect for arguments and return values.

Add the Go connector to a project

Step 1. Initialize the Go connector

Go version

The hasura/go connector requires Go version >=1.21.0. Please make sure you have the correct version installed.

Let's begin by initializing the connector on our project. In the example below, you'll see a familiar flow and use the hasura/go connector from the connector hub.

Run the following command:

ddn connector init my_go -i

• Select hasura/go from the list of connectors.
• Choose a port (press enter to accept the default recommended by the CLI).
• In this example, we've called the connector my_go. You can name it something descriptive.

What did this do?

This command created the following file structure in a my_subgraph/connector/my_go directory, with Go files in the functions folder being your connector's entrypoint:

.
├── .ddnignore
├── .gitignore
├── .hasura-connector
│  ├── ...
├── compose.yaml
├── functions
│  ├── hello.go
│  ├── types.generated.go
├── types
│  ├── connector.go
├── connector.generated.go
├── connector.go
├── main.go
├── go.mod
├── go.sum
├── Makefile
├── README.md
├── schema.generated.json

Step 2. Write business logic

The template code that ships with the Go connector provides some simple examples in the functions/hello.go file to help explain how it works.

Functions that have a Function prefix are allowed to be exposed as a read-only queries. For example:

// A hello argument
type HelloArguments struct {
  Greeting string `json:"greeting"` // value argument will be required
  Count    *int   `json:"count"`    // pointer arguments are optional
}

// A hello result
type HelloResult struct {
  Reply string `json:"reply"`
  Count int    `json:"count"`
}

// FunctionHello sends a hello message
func FunctionHello(ctx context.Context, state *types.State, arguments *HelloArguments) (*HelloResult, error) {
  count := 1
  if arguments.Count != nil {
    count = *arguments.Count + 1
  }
  return &HelloResult{
    Reply: fmt.Sprintf("Hi! %s", arguments.Greeting),
    Count: count,
  }, nil
}

Functions that have a Procedure prefix are allowed to be exposed as a mutation. For example:

// A create author argument
type CreateAuthorArguments struct {
  Name string `json:"name"`
}

// A create author result
type CreateAuthorResult struct {
  ID   int    `json:"id"`
  Name string `json:"name"`
}

// ProcedureCreateAuthor creates an author
func ProcedureCreateAuthor(ctx context.Context, state *types.State, arguments *CreateAuthorArguments) (*CreateAuthorResult, error) {
  return &CreateAuthorResult{
    ID:   1,
    Name: arguments.Name,
  }, nil
}

The CLI plugin infers the third argument of the function and generates the input argument. The first result type is generated as the response schema.

See more details in the documentation of hasura-ndc-go plugin.

Step 3. Track the new function

To add our function, we can use the following to generate the related metadata that will link together any functions in the functions directory and our API.

ddn connector introspect my_go
ddn command add my_go "*"

Step 4. Create a new API build and test

Next, let's create a new build of our supergraph:

ddn supergraph build local

Start your engines!

Don't forget to start your GraphQL engine using the following command.

From the root of your project, run:

ddn run docker-start

This reads the docker-start script from the context config at .hasura/context.yaml and starts your Hasura engine, any connectors, and observability tools.

You should see your command available, along with its documentation, in the GraphiQL explorer on the console which you should be able to access using:

Run:

ddn console --local

You can then test your new command with the following query:

query Hello {
  hello(greeting: "world") {
    reply
    count
  }
}

Privacy settings in some browsers

Your browser settings or privacy tools may prevent the Console from accessing your local Hasura instance. This could be due to features designed to protect your privacy and security. Should you encounter one of these issues, we recommend disabling these settings for the console.hasura.io domain.

Chrome and Firefox are the recommended browsers for the best experience with the Hasura Console including for local development.