README.md

Gremlin Server Client for Go

This library will allow you to connect to any graph database that supports TinkerPop3 using Go. This includes databases like JanusGraph and Neo4J. TinkerPop3 uses Gremlin Server to communicate with clients using either WebSockets or REST API. This library talks to Gremlin Server using WebSockets.

NB: Please note that this driver is currently looking for maintainers.

Installation

go get github.com/go-gremlin/gremlin

Usage

Export the list of databases you want to connect to as GREMLIN_SERVERS like so:-

export GREMLIN_SERVERS="ws://server1:8182/gremlin, ws://server2:8182/gremlin"

Import the library eg import "github.com/go-gremlin/gremlin".

Parse and save your cluster of services. You only need to do this once before submitting any queries (Perhaps in main()):-

	if err := gremlin.NewCluster(); err != nil {
		// handle error here
	}

Instead of using an environment variable, you can also pass the servers directly to NewCluster(). This is more convenient in development. For example:-

	if err := gremlin.NewCluster("ws://dev.local:8182/gremlin", "ws://staging.local:8182/gremlin"); err != nil {
		// handle error
	}

To actually run queries against the database, make sure the package is imported and issue a gremlin query like this:-

	data, err := gremlin.Query(`g.V()`).Exec()
	if err != nil  {
		// handle error
	}

data is a JSON array in bytes []byte if any data is returned otherwise it is nil. For example you can print it using:-

	fmt.Println(string(data))

or unmarshal it as desired.

You can also execute a query with bindings like this:-

	data, err := gremlin.Query(`g.V().has("name", userName).valueMap()`).Bindings(gremlin.Bind{"userName": "john"}).Exec()

You can also execute a query with Session, Transaction and Aliases

	aliases := make(map[string]string)
	aliases["g"] = fmt.Sprintf("%s.g", "demo-graph")
	session := "de131c80-84c0-417f-abdf-29ad781a7d04"  //use UUID generator
	data, err := gremlin.Query(`g.V().has("name", userName).valueMap()`).Bindings(gremlin.Bind{"userName": "john"}).Session(session).ManageTransaction(true).SetProcessor("session").Aliases(aliases).Exec()

Authentication

For authentication, you can set environment variables GREMLIN_USER and GREMLIN_PASS and create a Client, passing functional parameter OptAuthEnv

	auth := gremlin.OptAuthEnv()
	client, err := gremlin.NewClient("ws://remote.example.com:443/gremlin", auth)
	data, err = client.ExecQuery(`g.V()`)
	if err != nil {
		panic(err)
	}
	doStuffWith(data)

If you don't like environment variables you can authenticate passing username and password string in the following way:

	auth := gremlin.OptAuthUserPass("myusername", "mypass")
	client, err := gremlin.NewClient("ws://remote.example.com:443/gremlin", auth)
	data, err = client.ExecQuery(`g.V()`)
	if err != nil {
		panic(err)
	}
	doStuffWith(data)