siridb

README

Go-SiriDB-Connector

A SiriDB-Connector for the Go language

---

• Installation
• Usage
  • Single connection
  • SiriDB client
  • Logging

---

Installation

Simple install the package to your $GOPATH with the go tool from shell:

$ go get github.com/SiriDB/go-siridb-connector

Make sure Git is installed on your machine and in your system's PATH.

Usage

Go SiriDB Connector can be used to communicate with a single SiriDB server and a more advanced client is provided which can connect to multiple SiriDB servers so queries and inserts are balanced.

Single connection

This is some example code for how to use the Go-SiriDB-Connector as a single connection.

package main

import (
	"fmt"

	"github.com/SiriDB/go-siridb-connector"
)

func example(conn *siridb.Connection, ok chan bool) {
	// make sure the connection will be closed
	defer conn.Close()

	// create a new database with the following configuration
	options := make(map[string]interface{})
	options["dbname"] = "dbtest"
	options["time_precision"] = "s"
	options["buffer_size"] = 1024
	options["duration_num"] = "1w"
	options["duration_log"] = "1d"

	// using the default service account 'sa' and password 'siri'
	if res, err := conn.Manage("sa", "siri", siridb.AdminNewDatabase, options); err == nil {
		fmt.Printf("Manage result: %v\n", res)
	}

	// connect to database 'dbtest' using user 'iris' and password 'siri'
	// this is an example but usually you should do some error handling...
	if err := conn.Connect("iris", "siri", "dbtest"); err == nil {

		seriename := "serie-001"
		timestamp := 1471254705
		value := 1.5
		serie := make(map[string][][]interface{})
		serie[seriename] = [][]interface{}{{timestamp, value}}

		// insert data
		if res, err := conn.Insert(serie, 10); err == nil {
			fmt.Printf("Insert result: %s\n", res)
		}

		// perform a query
		if res, err := conn.Query("select * from *", 10); err == nil {
			fmt.Printf("Query result: %v\n", res)
		}
	}

	// send to the channel
	ok <- true
}

func main() {
	// create a new connection
	conn := siridb.NewConnection("localhost", 9000)

	// a connection will send output to stdout except when a log channel is used.
	// setup a log channel using:
	//  	conn.LogCh = myLogChannel

	// create a channel
	ok := make(chan bool)

	// run the example
	go example(conn, ok)

	// wait for the channel
	<-ok
}

SiriDB client

And one example for using the client. A client can be used for connecting to multiple siridb servers. Queries and inserts will be send to a random siridb server. When a connection is lost, it will retry to setup the connection each 30 seconds.

package main

import (
	"fmt"

	"github.com/SiriDB/go-siridb-connector"
)

func example(client *siridb.Client, ok chan bool) {
	// make sure the connection will be closed
	defer client.Close()

	client.Connect()

	// IsConnected() returns true if at least one server is connected.
	// Failed connections will retry creating a connection each 30 seconds.
	if client.IsConnected() {
		if res, err := client.Query("list series", 2); err == nil {
			fmt.Printf("Query result: %s\n", res)
		}
	} else {
		fmt.Println("not even a single server is connected...")
	}

	// send to the channel
	ok <- true
}

func main() {
	// create a new client
	client := siridb.NewClient(
		"iris",   // username
		"siri",   // password
		"dbtest", // database
		[][]interface{}{
			{"server1", 9000},
			{"server2", 9000},
		}, // siridb server(s)
		nil, // optional log channel
	)

	// create a channel
	ok := make(chan bool)

	// run the example
	go example(client, ok)

	// wait for the channel
	<-ok
}

Logging

Both a Connection and a Client can send logging to the standard output or to a channel for custom log handling.

For example you can create you own log handler like this:

func printLogs(logCh chan string) {
	for {
		msg := <-logCh
		fmt.Printf("Log: %s\n", msg)
	}
}

And set-up the channel like this:

logCh := make(chan string)
go printLogs(logCh)

If you plan to use the log channel with a Connection you should use the .LogCh property. For example:

conn := siridb.NewConnection(...) // create a new connection
conn.LogCh = logCh // set-up custom log channel

The Client simple accepts the channel as argument. For example:

client := siridb.NewClient(
	"user",
	"password",
	"database",
	[][]interface{}{...}, // array of servers, see SiriDB client for more info
	logCh, // logCh is allowed to be nil for logging to the standard output
)

Documentation

Index

• Constants
• type Buffer
  • func NewBuffer() *Buffer
  • func (buffer Buffer) Read()
• type Client
  • func NewClient(username, password, dbname string, hostlist [][]interface{}, logCh chan string) *Client
  • func (client Client) Close()
  • func (client Client) Connect()
  • func (client Client) Insert(data interface{}, timeout uint16) (interface{}, error)
  • func (client Client) InsertBin(data []byte, timeout uint16) (interface{}, error)
  • func (client Client) IsAvailable() bool
  • func (client Client) IsConnected() bool
  • func (client Client) Query(query string, timeout uint16) (interface{}, error)
• type Connection
  • func NewConnection(host string, port uint16) *Connection
  • func (conn *Connection) Close()
  • func (conn *Connection) Connect(username, password, dbname string) error
  • func (conn *Connection) Info() (interface{}, error)
  • func (conn *Connection) Insert(data interface{}, timeout uint16) (interface{}, error)
  • func (conn *Connection) InsertBin(data []byte, timeout uint16) (interface{}, error)
  • func (conn *Connection) IsConnected() bool
  • func (conn *Connection) Listen()
  • func (conn *Connection) Manage(username, password string, tp int, options map[string]interface{}) (interface{}, error)
  • func (conn *Connection) Query(query string, timeout uint16) (interface{}, error)
  • func (conn *Connection) Send(tp uint8, data interface{}, timeout uint16) (interface{}, error)
  • func (conn *Connection) SendBin(tp uint8, data []byte, timeout uint16) (interface{}, error)
  • func (conn *Connection) ToString() string
• type Error
  • func NewError(s string, t uint8) *Error
  • func (e *Error) Error() string
  • func (e *Error) Type() uint8
• type Host
  • func NewHost(host string, port uint16, logCh chan string) *Host
• type Pkg
  • func NewPkg(b []byte) (*Pkg, error)
  • func (p *Pkg) Data(b *[]byte, size uint32)

Constants

const AdminChangePassword = 1

AdminChangePassword for changing a server account password

const AdminDropAccount = 2

AdminDropAccount for dropping a server account

const AdminDropDatabase = 6

AdminDropDatabase for dropping a database

const AdminGetAccounts = 65

AdminGetAccounts for getting all accounts on a siridb server

const AdminGetDatabases = 66

AdminGetDatabases for getting all database running on a siridb server

const AdminGetVersion = 64

AdminGetVersion for getting the siridb server version

const AdminNewAccount = 0

AdminNewAccount for create a new manage server account

const AdminNewDatabase = 3

AdminNewDatabase for creating a new database

const AdminNewPool = 4

AdminNewPool for expanding a database with a new pool

const AdminNewReplica = 5

AdminNewReplica for expanding a database with a new replica

const AppVersion = "1.0.14"

AppVersion exposes version information

const CprotoAckAdmin = 32

CprotoAckAdmin on successful manage server request

const CprotoAckAdminData = 33

CprotoAckAdminData on successful manage server request with data

const CprotoErr = 70

CprotoErr on server error

const CprotoErrAdmin = 96

CprotoErrAdmin on manage server error with message

const CprotoErrAdminInvalidRequest = 97

CprotoErrAdminInvalidRequest on invalid manage server request

const CprotoErrAuthCredentials = 72

CprotoErrAuthCredentials on server error

const CprotoErrAuthUnknownDb = 73

CprotoErrAuthUnknownDb on server error

const CprotoErrFile = 75

CprotoErrFile on server error

const CprotoErrInsert = 66

CprotoErrInsert on insert error

const CprotoErrLoadingDb = 74

CprotoErrLoadingDb on server error

const CprotoErrMsg = 64

CprotoErrMsg general error

const CprotoErrNotAuthenticated = 71

CprotoErrNotAuthenticated on server error

const CprotoErrPool = 68

CprotoErrPool on server error

const CprotoErrQuery = 65

CprotoErrQuery on query error

const CprotoErrServer = 67

CprotoErrServer on server error

const CprotoErrUserAccess = 69

CprotoErrUserAccess on server error

const CprotoReqAdmin = 32

CprotoReqAdmin for a manage server request

const CprotoReqAuth = 2

CprotoReqAuth for authentication

const CprotoReqFileGroups = 9

CprotoReqFileGroups for requesting a groups.dat file

const CprotoReqFileServers = 7

CprotoReqFileServers for requesting a server.dat file

const CprotoReqFileUsers = 8

CprotoReqFileUsers for requesting a users.dat file

const CprotoReqInfo = 4

CprotoReqInfo for requesting database info

const CprotoReqInsert = 1

CprotoReqInsert for sending inserts

const CprotoReqLoadDB = 5

CprotoReqLoadDB for loading a new database

const CprotoReqPing = 3

CprotoReqPing for ping on the connection

const CprotoReqQuery = 0

CprotoReqQuery for sending queries

const CprotoReqRegisterServer = 6

CprotoReqRegisterServer for registering a new server

const CprotoResAck = 3

CprotoResAck on ack

const CprotoResAuthSuccess = 2

CprotoResAuthSuccess on authentication success

const CprotoResFile = 5

CprotoResFile on request file response

const CprotoResInfo = 4

CprotoResInfo on database info response

const CprotoResInsert = 1

CprotoResInsert on insert response

const CprotoResQuery = 0

CprotoResQuery on query response

const HeaderSize = 8

HeaderSize if the size of a package header.

Types

type Buffer

type Buffer struct {
	DataCh chan *Pkg
	ErrCh  chan error
	// contains filtered or unexported fields
}

Buffer is used to read data from a connection.

func NewBuffer

func NewBuffer() *Buffer

NewBuffer retur a pointer to a new buffer.

func (Buffer) Read

func (buffer Buffer) Read()

Read listens on a connection for data.

type Client

type Client struct {
	PingInterval time.Duration
	// contains filtered or unexported fields
}

Client can be used to communicate with a SiriDB cluster.

func NewClient

func NewClient(username, password, dbname string, hostlist [][]interface{}, logCh chan string) *Client

NewClient returns a pointer to a new client object. Example hostlist:

[][]interface{}{
	 {"myhost1", 9000}, 		// hostname/ip and port are required
  {"myhost2", 9000, 2},      // an optional integer value can be used as weight
								// (default weight is 1)
  {"myhost3", 9000, true},   // if true is added as third argument the host
								// will be used only when other hosts are not available
}

func (Client) Close

func (client Client) Close()

Close will close all open connections.

func (Client) Connect

func (client Client) Connect()

Connect to SiriDB. make sure to initialize random: rand.Seed(time.Now().Unix())

func (Client) Insert

func (client Client) Insert(data interface{}, timeout uint16) (interface{}, error)

Insert data into a SiriDB database.

func (Client) InsertBin

func (client Client) InsertBin(data []byte, timeout uint16) (interface{}, error)

InsertBin binary data into a SiriDB database.

func (Client) IsAvailable

func (client Client) IsAvailable() bool

IsAvailable return true if at least one connection is connected

func (Client) IsConnected

func (client Client) IsConnected() bool

IsConnected return true if at least one connection is connected

func (Client) Query

func (client Client) Query(query string, timeout uint16) (interface{}, error)

Query a SiriDB database.

type Connection

type Connection struct {
	OnClose func()
	LogCh   chan string
	// contains filtered or unexported fields
}

Connection is a SiriDB Connection. Port should be the client port.

func NewConnection

func NewConnection(host string, port uint16) *Connection

NewConnection creates a new connection connection

func (*Connection) Close

func (conn *Connection) Close()

Close will close an open connection.

func (*Connection) Connect

func (conn *Connection) Connect(username, password, dbname string) error

Connect to a SiriDB connection.

func (*Connection) Info

func (conn *Connection) Info() (interface{}, error)

Info returns siridb info

func (*Connection) Insert

func (conn *Connection) Insert(data interface{}, timeout uint16) (interface{}, error)

Insert sends data to a SiriDB database.

func (*Connection) InsertBin

func (conn *Connection) InsertBin(data []byte, timeout uint16) (interface{}, error)

InsertBin sends binary data to a SiriDB database.

func (*Connection) IsConnected

func (conn *Connection) IsConnected() bool

IsConnected returns true when connected.

func (*Connection) Listen

func (conn *Connection) Listen()

Listen to data channels

func (*Connection) Manage

func (conn *Connection) Manage(username, password string, tp int, options map[string]interface{}) (interface{}, error)

Manage send a manage server request.

func (*Connection) Query

func (conn *Connection) Query(query string, timeout uint16) (interface{}, error)

Query sends a query and returns the result.

func (*Connection) Send

func (conn *Connection) Send(tp uint8, data interface{}, timeout uint16) (interface{}, error)

Send is used to send bytes

func (*Connection) SendBin

func (conn *Connection) SendBin(tp uint8, data []byte, timeout uint16) (interface{}, error)

SendBin is used to send bytes

func (*Connection) ToString

func (conn *Connection) ToString() string

ToString returns a string representing the connection and port.

type Error

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

Error can be returned by the siridb package.

func NewError

func NewError(s string, t uint8) *Error

NewError returns a pointer to a new Error.

func (*Error) Error

func (e *Error) Error() string

Error returns the error msg.

func (*Error) Type

func (e *Error) Type() uint8

Type returns the error type.

type Host

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

Host is where a client saves a connection

func NewHost

func NewHost(host string, port uint16, logCh chan string) *Host

NewHost return a pointer to a new host.

type Pkg

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

Pkg contains of a header and data.

func NewPkg

func NewPkg(b []byte) (*Pkg, error)

NewPkg returns a poiter to a new pkg.

func (*Pkg) Data

func (p *Pkg) Data(b *[]byte, size uint32)

Data sets package data