goBolt

README

Go-Bolt - GoLang Bolt Driver

Implements Neo4j Bolt Protocol Versions 1-4

go get -u github.com/mindstand/go-bolt

(Disclaimer) This repository is still a major work in progress

Features

• Supports bolt protocol versions 1-4
• Supports multi db in bolt protocol v4
• Connection Pooling
• bolt+routing for casual clusters
• TLS support

Current todo's

(Issues will be updated)

• Documentation across entire repository
• Unit/integration testing across the entire repository for all protocol versions
• Support for neo4j bookmarks

Long term goals

• Cypher checks preflight
• Benchmark Testing

Thanks to:

• @johnnadratowski: for your original implementation of the bolt driver in go. We used the design as a basis for this driver!

Current example

This will be changed, this is the main integration test at the moment

client, err := NewClient(WithBasicAuth("neo4j", "changme"), WithHostPort("0.0.0.0", 7687))
if err != nil {
    panic(err)
}

driver, err := client.NewDriver()
if err != nil {
    panic(err)
}

conn, err := driver.Open(bolt_mode.WriteMode)
if err != nil {
    panic(err)
}

all, m, err := conn.Query("create (:TestNode{uuid:$id})", map[string]interface{}{
   "id": "random_id",
})
log.Tracef("rows: %v, %v, %v", all, m, err)

err = conn.Close()
if err != nil {
    panic(err)
}

Documentation

Overview

Package goBolt implements drivers for the Neo4J Bolt Protocol Versions 1-4.

There are some limitations to the types of collections the internalDriver supports. Specifically, maps should always be of type map[string]interface{} and lists should always be of type []interface{}. It doesn't seem that the Bolt protocol supports uint64 either, so the biggest number it can send right now is the int64 max.

The URL format is: `bolt://(user):(password)@(host):(port)` Schema must be `bolt`. User and password is only necessary if you are authenticating. TLS is supported by using query parameters on the connection string, like so: `bolt://host:port?tls=true&tls_no_verify=false`

The supported query params are:

* timeout - the number of seconds to set the connection timeout to. Defaults to 60 seconds. * tls - Set to 'true' or '1' if you want to use TLS encryption * tls_no_verify - Set to 'true' or '1' if you want to accept any server certificate (for testing, not secure) * tls_ca_cert_file - path to a custom ca cert for a self-signed TLS cert * tls_cert_file - path to a cert file for this client (need to verify this is processed by Neo4j) * tls_key_file - path to a key file for this client (need to verify this is processed by Neo4j)

Errors returned from the API support wrapping, so if you receive an error from the library, it might be wrapping other errors. You can get the innermost error by using the `InnerMost` method. Failure messages from Neo4J are reported, along with their metadata, as an error. In order to get the failure message metadata from a wrapped error, you can do so by calling `err.(*errors.Error).InnerMost().(messages.FailureMessage).Metadata`

If there is an error with the database connection, you should get a sql/internalDriver ErrBadConn as per the best practice recommendations of the Golang SQL Driver. However, this error may be wrapped, so you might have to call `InnerMost` to get it, as specified above.

Index

• type Client
  • func (c *Client) NewDriver() (IDriver, error)
  • func (c *Client) NewDriverPool(size int) (IDriverPool, error)
• type ConnectionPooledObjectFactory
  • func (c *ConnectionPooledObjectFactory) ActivateObject(ctx context.Context, object *pool.PooledObject) error
  • func (c *ConnectionPooledObjectFactory) DestroyObject(ctx context.Context, object *pool.PooledObject) error
  • func (c *ConnectionPooledObjectFactory) MakeObject(ctx context.Context) (*pool.PooledObject, error)
  • func (c *ConnectionPooledObjectFactory) PassivateObject(ctx context.Context, object *pool.PooledObject) error
  • func (c *ConnectionPooledObjectFactory) ValidateObject(ctx context.Context, object *pool.PooledObject) bool
• type Driver
  • func (d *Driver) Open(mode bolt_mode.AccessMode) (connection.IConnection, error)
• type DriverPool
  • func (d *DriverPool) Close() error
  • func (d *DriverPool) Open(mode bolt_mode.AccessMode) (connection.IConnection, error)
  • func (d *DriverPool) Reclaim(conn connection.IConnection) error
• type IClient
  • func NewClient(opts ...Opt) (IClient, error)
• type IDriver
• type IDriverPool
• type Opt
  • func WithBasicAuth(username, password string) Opt
  • func WithChunkSize(size uint16) Opt
  • func WithConnectionString(connString string) Opt
  • func WithHostPort(host string, port int) Opt
  • func WithProtocolVersionGreaterThan(version int) Opt
  • func WithProtocolVersionLessThan(version int) Opt
  • func WithProtocolVersionNegotiation() Opt
  • func WithRouting() Opt
  • func WithStrictProtocolVersion(version int) Opt
  • func WithTLS(cacertPath, certPath, keyPath string, tlsNoVerify bool) Opt
  • func WithTimeout(timeout time.Duration) Opt
• type RoutingDriverPool
  • func (r *RoutingDriverPool) Close() error
  • func (r *RoutingDriverPool) Open(mode bolt_mode.AccessMode) (connection.IConnection, error)
  • func (r *RoutingDriverPool) Reclaim(conn connection.IConnection) error

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func (*Client) NewDriver

func (c *Client) NewDriver() (IDriver, error)

func (*Client) NewDriverPool

func (c *Client) NewDriverPool(size int) (IDriverPool, error)

type ConnectionPooledObjectFactory

type ConnectionPooledObjectFactory struct {
	// contains filtered or unexported fields
}

func (*ConnectionPooledObjectFactory) ActivateObject

func (c *ConnectionPooledObjectFactory) ActivateObject(ctx context.Context, object *pool.PooledObject) error

func (*ConnectionPooledObjectFactory) DestroyObject

func (c *ConnectionPooledObjectFactory) DestroyObject(ctx context.Context, object *pool.PooledObject) error

func (*ConnectionPooledObjectFactory) MakeObject

func (c *ConnectionPooledObjectFactory) MakeObject(ctx context.Context) (*pool.PooledObject, error)

func (*ConnectionPooledObjectFactory) PassivateObject

func (c *ConnectionPooledObjectFactory) PassivateObject(ctx context.Context, object *pool.PooledObject) error

func (*ConnectionPooledObjectFactory) ValidateObject

func (c *ConnectionPooledObjectFactory) ValidateObject(ctx context.Context, object *pool.PooledObject) bool

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

standard driver is basically a factory its not keeping track of connections connections are expected to be killed when done

func (*Driver) Open

func (d *Driver) Open(mode bolt_mode.AccessMode) (connection.IConnection, error)

mode doesn't matter since its not a pooled or routing driver

type DriverPool

type DriverPool struct {
	// contains filtered or unexported fields
}

func (*DriverPool) Close

func (d *DriverPool) Close() error

func (*DriverPool) Open

func (d *DriverPool) Open(mode bolt_mode.AccessMode) (connection.IConnection, error)

func (*DriverPool) Reclaim

func (d *DriverPool) Reclaim(conn connection.IConnection) error

type IClient

type IClient interface {
	// opens a new internalDriver to neo4j
	NewDriver() (IDriver, error)

	// opens a internalDriver pool to neo4j
	NewDriverPool(size int) (IDriverPool, error)
}

func NewClient

func NewClient(opts ...Opt) (IClient, error)

type IDriver

type IDriver interface {
	Open(mode bolt_mode.AccessMode) (connection.IConnection, error)
}

bolt+routing will not work for non pooled connections

type IDriverPool

type IDriverPool interface {
	// Open opens a Neo-specific connection.
	Open(mode bolt_mode.AccessMode) (connection.IConnection, error)
	Reclaim(connection.IConnection) error
	Close() error
}

type Opt

type Opt func(*Client) error

func WithBasicAuth

func WithBasicAuth(username, password string) Opt

allows authentication with basic auth

func WithChunkSize

func WithChunkSize(size uint16) Opt

allows setting chunk size

func WithConnectionString

func WithConnectionString(connString string) Opt

WithConnectionString provides client option with connection string

func WithHostPort

func WithHostPort(host string, port int) Opt

allows setting the host and port of neo4j

func WithProtocolVersionGreaterThan

func WithProtocolVersionGreaterThan(version int) Opt

func WithProtocolVersionLessThan

func WithProtocolVersionLessThan(version int) Opt

func WithProtocolVersionNegotiation

func WithProtocolVersionNegotiation() Opt

tells client to negotiate version

func WithRouting

func WithRouting() Opt

allows setting protocol to bolt+routing

func WithStrictProtocolVersion

func WithStrictProtocolVersion(version int) Opt

requires protocol version

func WithTLS

func WithTLS(cacertPath, certPath, keyPath string, tlsNoVerify bool) Opt

allows authentication with tls

func WithTimeout

func WithTimeout(timeout time.Duration) Opt

tells client what timeout it should use

type RoutingDriverPool

type RoutingDriverPool struct {
	// contains filtered or unexported fields
}

func (*RoutingDriverPool) Close

func (r *RoutingDriverPool) Close() error

func (*RoutingDriverPool) Open

func (r *RoutingDriverPool) Open(mode bolt_mode.AccessMode) (connection.IConnection, error)

func (*RoutingDriverPool) Reclaim

func (r *RoutingDriverPool) Reclaim(conn connection.IConnection) error