Getting Started

Prerequisites

• gremlin-go requires Golang 1.22 or later, please see Go Download for more details on installing Golang.
• A basic understanding of Go Modules
• A project set up which uses Go Modules

Installing the Gremlin-Go as a dependency

To install the Gremlin-Go as a dependency for your project, run the following in the root directory of your project that contains your go.mod file:

go get github.com/apache/tinkerpop/gremlin-go/v3[optionally append @<version>, such as @v3.5.3 - note this requires GO111MODULE=on]

Available versions can be found at pkg.go.dev.

After running the go get command, your go.mod file should contain something similar to the following:

module gremlin-go-example

go 1.22

require github.com/apache/tinkerpop/gremlin-go/v3 v<version>

If it does, then this means Gremlin-Go was successfully installed as a dependency of your project.

You will need to run go mod tidy to import the remaining dependencies of the gremlin-go driver (if your IDE does not do so automatically), after which you should see an updated go.mod file:

module gremlin-go-example

go 1.22

require github.com/apache/tinkerpop/gremlin-go v0.0.0-20220131225152-54920637bf94

require (
	github.com/google/uuid v1.3.0 // indirect
	github.com/gorilla/websocket v1.4.2 // indirect
	github.com/nicksnyder/go-i18n/v2 v2.1.2 // indirect
	golang.org/x/text v0.3.7 // indirect
)

As well as a populated go.sum file.

if there are no usages for gremlingo found, it will remove the require from go.mod and not import dependencies.

Simple usage

For instructions on simple usage, including connecting, connection settings, aliases and more, check out the Gremlin-Go section in the Tinkerpop Documentation.

Troubleshooting

Can't establish connection and get any result

• Verify you are using valid server protocol and path. Note that for secure connection wss should be used.
• Verify firewall settings.

Local server doesn't have valid certificate

• Set connection option &tls.Config{InsecureSkipVerify: true}

Client hangs on requests with large amount of data

• Increase read buffer size by settings connection option readBufferSize.

Gremlin-Go Development

Design Architecture

See Gremlin-Go Design Overview

Building Directly

To build the driver you must install go. The following command can be used to build the driver: go build <path to source code>

Code Styling and Linting

Before generating a pull request, you should manually run the following to ensure correct code styling and fix any issues indicated by the linters.

Formatting files with Gofmt

To ensure clean and readable code Gofmt is used.

Navigate to file path in a terminal window and run:

go fmt

Gofmt will recursively check for and format .go files.

Note: If your IDE of choice is GoLand, code can be automatically formatted with Gofmt on file save. Instructions on how to enable this feature can be found here.

Using the Linter and staticcheck

Run go vet and staticcheck and correct any errors.

go vet is installed when you install go, and can be run with:

go vet <path to source code>

Please review the staticcheck documentation for more details on installing staticcheck. It can be run with:

staticcheck <path to source code>

Testing with Docker

Docker allows you to test the driver without installing any dependencies. Gremlin Go uses Docker for all of its testing. Please make sure Docker is installed and running on your system. You will need to install both Docker Engine and Docker Compose, which are included in Docker Desktop.

The docker compose environment variable GREMLIN_SERVER specifies the Gremlin server docker image to use, i.e. an image with the tag tinkerpop/gremlin-server:$GREMLIN_SERVER, and is a required environment variable. This also requires the specified docker image to exist, either locally or in Docker Hub.

Running mvn clean install -pl gremlin-server -DskipTests -DskipIntegrationTests=true -Dci -am in the main tinkerpop directory will automatically build a local SNAPSHOT Gremlin server image. If your OS Platform cannot build a local SNAPSHOT Gremlin server through maven, it is recommended to use the latest released server version from Docker Hub (do not use GREMLIN_SERVER=latest, use actual version number, e.g. GREMLIN_SERVER=3.5.x or GREMLIN_SERVER=3.6.x).

The docker compose environment variable HOME specifies the user home directory for mounting volumes during test image set up. This variable is set by default in Unix/Linux, but will need to be set for Windows, for example, run $env:HOME=$env:USERPROFILE in PowerShell.

There are different ways to launch the test suite and set the GREMLIN_SERVER environment variable depending on your Platform:

• Run Maven commands, e.g. mvn clean install inside of tinkerpop/gremlin-go, or mvn clean install -pl gremlin-go inside of tinkerpop (platform-agnostic - recommended)
• Run the run.sh script, which sets GREMLIN_SERVER by default. Run ./run.sh -h for usage information (Unix/Linux - recommended).
• Add GREMLIN_SERVER=<server-image-version> and HOME=<user-home-directory> to an .env file inside gremlin-go and run docker compose up --exit-code-from gremlin-go-integration-tests (Platform-agnostic).
• Run GREMLIN_SERVER=<server-image-version> docker compose up --exit-code-from gremlin-go-integration-tests in Unix/Linux.
• Run $env:GREMLIN_SERVER="<server-image-version>";$env:HOME=$env:USERPROFILE;docker compose up --exit-code-from gremlin-go-integration-tests in Windows PowerShell.

You should see exit code 0 upon successful completion of the test suites. Run docker compose down to remove the service containers (not needed if you executed Maven commands or run.sh), or docker compose down --rmi all to remove the service containers while deleting all used images.