avatica

README

Apache Phoenix/Avatica SQL Driver

An Apache Phoenix/Avatica driver for Go's database/sql package

Getting started

Install using the go tool or your dependency management tool:

$ go get github.com/Boostport/avatica

Usage

The Phoenix/Avatica driver implements Go's database/sql/driver interface, so, import Go's database/sql package and the driver:

import "database/sql"
import _ "github.com/Boostport/avatica"

db, err := sql.Open("avatica", "http://localhost:8765")

Then simply use the database connection to query some data, for example:

rows := db.Query("SELECT COUNT(*) FROM test")

DSN (Data Source Name)

The DSN has the following format (optional parts are marked by square brackets):

http://address:ports[?parameter1=value&...parameterN=value]

In other words, the scheme (http), address and port is mandatory, but the parameters are optional.

The following parameters are supported:

location

The location will be set as the location of unserialized time.Time values. It must be a valid timezone. If you want to use the local timezone, use Local. By default, this is set to UTC.

maxRowsTotal

The maxRowsTotal parameter sets the maximum number of rows to return for a given query. By default, this is set to -1, so that there is no limit on the number of rows returned.

frameMaxSize

The frameMaxSize parameter sets the maximum number of rows to return in a frame. Depending on the number of rows returned and subject to the limits of maxRowsTotal, a query result set can contain rows in multiple frames. These additional frames are then fetched on a as-needed basis. frameMaxSize allows you to control the number of rows in each frame to suit your application's performance profile. By default this is set to -1, so that there is no limit on the number of rows in a frame.

time.Time support

The following Phoenix/Avatica datatypes are automatically converted to and from time.Time: TIME, DATE and TIMESTAMP.

It is important to understand that avatica and the underlying database ignores the timezone. If you save a time.Time to the database, the timezone is ignored and vice-versa. This is why you need to make sure the location parameter in your DSN is set to the same value as the location of the time.Time values you are inserting into the database.

We recommend using UTC, which is the default value of location.

Version compatibility

Driver Version	Phoenix Version	Calcite/Avatica Version
1.0.0	4.8.0	1.8.0

Development

To run tests, but skip tests in the vendor directory, run:

go test $(go list ./... | grep -v /vendor/)

The driver is not feature-complete yet, so contributions are very appreciated.

Updating protocol buffer definitions

To update the procotol buffer definitions, update CALCITE_VER in gen-protobuf.bat and gen-protobuf.sh to match the version included by Phoenix and then run the appropriate script for your platform.

About the moby.yml file

The moby.yml file is used by our internal tool to automatically reload and test the code during development. We hope to have this tool open-sourced soon.

License

The driver is licensed under the Apache 2 license.

Documentation

Overview

Package avatica provides an Apache Phoenix Query Server/Avatica driver for Go's database/sql package.

Quickstart

Import the database/sql package along with the avatica driver.

import "database/sql"
import _ "github.com/Boostport/avatica"

db, err := sql.Open("avatica", "http://phoenix-query-server:8765")

See https://github.com/Boostport/avatica#usage for more details

Index

• Constants
• func NewHTTPClient(host string) *httpClient
• type Config
  • func ParseDSN(dsn string) (*Config, error)
• type Driver
  • func (a *Driver) Open(dsn string) (driver.Conn, error)
• type ErrorCode
• type RPCMetadata
• type ResponseError
  • func (r ResponseError) Error() string
  • func (r ResponseError) Name() string
• type SQLState

Constants

const (
	Eunknown int8 = iota
	Efatal
	Eerror
	Ewarning
)

Error severity codes

Functions

func NewHTTPClient

func NewHTTPClient(host string) *httpClient

NewHTTPClient creates a new httpClient from a host.

Types

type Config

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

Config is a configuration parsed from a DSN string

func ParseDSN

func ParseDSN(dsn string) (*Config, error)

ParseDSN parses a DSN string to a Config

type Driver

type Driver struct{}

Driver is exported to allow it to be used directly.

func (*Driver) Open

func (a *Driver) Open(dsn string) (driver.Conn, error)

Open a Connection to the server. See https://github.com/Boostport/avatica#dsn for more information on how the DSN is formatted.

type ErrorCode

type ErrorCode uint32

type RPCMetadata

type RPCMetadata struct {
	ServerAddress string
}

RPCMetadata contains metadata about the call that caused the error.

type ResponseError

type ResponseError struct {
	Exceptions    []string
	HasExceptions bool
	ErrorMessage  string
	Severity      int8
	ErrorCode     ErrorCode
	SqlState      SQLState
	Metadata      *RPCMetadata
}

ResponseError is an error type that contains detailed information on what caused the server to return an error.

func (ResponseError) Error

func (r ResponseError) Error() string

func (ResponseError) Name

func (r ResponseError) Name() string

Name returns the name of the error encountered by the server.

type SQLState

type SQLState string