voltdb-client-go

README

VoltDB Golang Client Library

The VoltDB golang client library implements the native VoltDB wire protocol. You can use the library to connect to a VoltDB cluster, invoke stored procedures and read responses.

Installation

go get -v -u github.com/VoltDB/voltdb-client-go/voltdbclient

Requirements

Recommend version:
go version >= 1.9

Usage

As database/sql driver

package main

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	_ "github.com/VoltDB/voltdb-client-go/voltdbclient"
)

func main() {
	// If using a version of VoltDB server prior to 5.2, then
	// set the version of the wire protocol to 0.  The default
	// value 1, indicates a server version of 5.2 or later.
	// voltdbclient.ProtocolVersion = 0

	db, err := sql.Open("voltdb", "localhost:21212")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	err = db.Ping()
	if err != nil {
		log.Fatal(err)
	}
	rows, err := db.Query("HELLOWORLD.select", "French")
	if err != nil {
		log.Fatal(err)
	}
	printRows(rows)

	// with prepared statement
	stmt, err := db.Prepare("select * from HELLOWORLD where dialect = ?")
	if err != nil {
		log.Fatal(err)
	}

	rows, err = stmt.Query("French")
	if err != nil {
		log.Fatal(err)
	}
	printRows(rows)

}

func printRows(rows *sql.Rows) {
	for rows.Next() {
		var hello string
		var world string
		var dialect string
		err := rows.Scan(&hello, &world, &dialect)
		if err != nil {
			fmt.Println(err)
			break
		}
		fmt.Printf("SUCCESS: %s %s %s\n", hello, world, dialect)
	}
}

Client API

The VoltDB golang client implements the interfaces specified in the database/sql/driver package. The interfaces specified by database/sql/driver are typically used to implement a driver to be used with the golang database/sql package.

The code here can be used as a driver in this manner; it can also be used as a stand alone client.

The VoltDB golang client supports a VoltDB specific asynchronous api in addition to the database/sql/driver api. The VoltDB api also includes column accessors for VoltDB specific types. The details of the VoltDB api can be found in the godoc.

Examples

The VoltDB golang client includes three examples. There is a simple hello world example and a similar example that uses the asynchronous api. There is also an example that uses the client with the database/sql/driver api only.

Wire Protocol

By default, version 1 of the VoltDB wire protocol is used; this is suitable for VoltDB server version 5.2 or later. Set the wire protocol version to 0 for use with an older server. See the 'driver_hello_world' example.

FAQ

How do I manage connection pools?

When using database/sql driver, connection pools are automatically managed for you. However there is a couple of options offered for custom control such as SetConnMaxLifetime, SetMaxIdleConns and SetMaxOpenConns

Micro benchmarks

When doing development on this client, before adding new changes first you need to run benchmarks of the client . We have included helper make rules for this just run make bench-old which when done will create old.bench file on the root of the project.

You can then go ahead and make the changes, when done you need to run benchmarks with the new changes by running make bench-new which will create new.bench.

Compare the two benchmarks with make benchcmp. This will help you to see if there were any regressions introduced by the changes. This rule depends on benchcmp tool to be installed, if that tool is missing run make deps to install it.