gocql

package module
v0.0.0-...-03f7e4f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 23, 2014 License: BSD-3-Clause Imports: 16 Imported by: 0

README

gocql

Build Status GoDoc

Package Status: Alpha

Package gocql implements a fast and robust Cassandra client for the Go programming language.

Project Website: http://gocql.github.io/
API documentation: http://godoc.org/github.com/gocql/gocql
Discussions: https://groups.google.com/forum/#!forum/gocql

Installation

go get github.com/gocql/gocql

Features

  • Modern Cassandra client for Cassandra 1.2 and 2.0
  • Automatic type conversations between Cassandra and Go
    • Support for all common types including sets, lists and maps
    • Custom types can implement a Marshaler and Unmarshaler interface
    • Strict type conversations without any loss of precision
    • Built-In support for UUIDs (version 1 and 4)
  • Support for logged, unlogged and counter batches
  • Cluster management
    • Automatic reconnect on connection failures with exponential falloff
    • Round robin distribution of queries to different hosts
    • Round robin distribution of queries to different connections on a host
    • Each connection can execute up to 128 concurrent queries
  • Iteration over paged results with configurable page size
  • Optional frame compression (using snappy)
  • Automatic query preparation
  • Support for query tracing

Please visit the Roadmap page to see what is on the horizion.

Example

package main

import (
	"fmt"
	"log"

	"github.com/gocql/gocql"
)

func main() {
	// connect to the cluster
	cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
	cluster.Keyspace = "example"
	cluster.Consistency = gocql.Quorum
	session, _ := cluster.CreateSession()
	defer session.Close()

	// insert a tweet
	if err := session.Query(`INSERT INTO tweet (timeline, id, text) VALUES (?, ?, ?)`,
		"me", gocql.TimeUUID(), "hello world").Exec(); err != nil {
		log.Fatal(err)
	}

	var id gocql.UUID
	var text string

	// select a single tweet
	if err := session.Query(`SELECT id, text FROM tweet WHERE timeline = ? LIMIT 1`,
		"me").Consistency(gocql.One).Scan(&id, &text); err != nil {
		log.Fatal(err)
	}
	fmt.Println("Tweet:", id, text)

	// list all tweets
	iter := session.Query(`SELECT id, text FROM tweet WHERE timeline = ?`, "me").Iter()
	for iter.Scan(&id, &text) {
		fmt.Println("Tweet:", id, text)
	}
	if err := iter.Close(); err != nil {
		log.Fatal(err)
	}
}

Other Projects

  • cqlc generates gocql compliant code from your Cassandra schema so that you can write type safe CQL statements in Go with a natural query syntax.
  • gocqldriver is the predecessor of gocql based on Go's "database/sql" package. This project isn't maintained anymore, because Cassandra wasn't a good fit for the traditional "database/sql" API. Use this package instead.

License

Copyright (c) 2012-2014 The gocql Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Documentation

Overview

Package gocql implements a fast and robust Cassandra driver for the Go programming language.

Copyright (c) 2012 The gocql Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file. This file will be the future home for more policies

The uuid package can be used to generate and parse universally unique identifiers, a standardized format in the form of a 128 bit number.

http://tools.ietf.org/html/rfc4122

Index

Constants

View Source 
const (
	VariantNCSCompat = 0
	VariantIETF      = 2
	VariantMicrosoft = 6
	VariantFuture    = 7
)

Variables

View Source 
var (
	ErrNoHosts       = errors.New("no hosts provided")
	ErrNoConnections = errors.New("no connections were made in startup time frame")
)
View Source 
var (
	ErrNotFound     = errors.New("not found")
	ErrUnavailable  = errors.New("unavailable")
	ErrProtocol     = errors.New("protocol error")
	ErrUnsupported  = errors.New("feature not supported")
	ErrTooManyStmts = errors.New("too many statements")
)

Functions

func Marshal 

func Marshal(info *TypeInfo, value interface{}) ([]byte, error)

Marshal returns the CQL encoding of the value for the Cassandra internal type described by the info parameter.

func Unmarshal 

func Unmarshal(info *TypeInfo, data []byte, value interface{}) error

Unmarshal parses the CQL encoded data based on the info parameter that describes the Cassandra internal data type and stores the result in the value pointed by value.

Types

type Authenticator 

type Authenticator interface {
	Challenge(req []byte) (resp []byte, auth Authenticator, err error)
	Success(data []byte) error
}

type Batch 

type Batch struct {
	Type    BatchType
	Entries []BatchEntry
	Cons    Consistency
	// contains filtered or unexported fields
}

func NewBatch 

func NewBatch(typ BatchType) *Batch

NewBatch creates a new batch operation without defaults from the cluster

func (*Batch) Query 

func (b *Batch) Query(stmt string, args ...interface{})

Query adds the query to the batch operation

func (*Batch) RetryPolicy 

func (b *Batch) RetryPolicy(r RetryPolicy) *Batch

RetryPolicy sets the retry policy to use when executing the batch operation

type BatchEntry 

type BatchEntry struct {
	Stmt string
	Args []interface{}
}

type BatchType 

type BatchType int
const (
	LoggedBatch   BatchType = 0
	UnloggedBatch BatchType = 1
	CounterBatch  BatchType = 2
)

type Cluster 

type Cluster interface {
	HandleError(conn *Conn, err error, closed bool)
	HandleKeyspace(conn *Conn, keyspace string)
}

type ClusterConfig 

type ClusterConfig struct {
	Hosts           []string      // addresses for the initial connections
	CQLVersion      string        // CQL version (default: 3.0.0)
	ProtoVersion    int           // version of the native protocol (default: 2)
	Timeout         time.Duration // connection timeout (default: 600ms)
	DefaultPort     int           // default port (default: 9042)
	Keyspace        string        // initial keyspace (optional)
	NumConns        int           // number of connections per host (default: 2)
	NumStreams      int           // number of streams per connection (default: 128)
	DelayMin        time.Duration // minimum reconnection delay (default: 1s)
	DelayMax        time.Duration // maximum reconnection delay (default: 10min)
	StartupMin      int           // wait for StartupMin hosts (default: len(Hosts)/2+1)
	StartupTimeout  time.Duration // amount of to wait for a connection (default: 5s)
	Consistency     Consistency   // default consistency level (default: Quorum)
	Compressor      Compressor    // compression algorithm (default: nil)
	Authenticator   Authenticator // authenticator (default: nil)
	RetryPolicy     RetryPolicy   // Default retry policy to use for queries (default: 0)
	SocketKeepalive time.Duration // The keepalive period to use, enabled if > 0 (default: 0)
}

ClusterConfig is a struct to configure the default cluster implementation of gocoql. It has a varity of attributes that can be used to modify the behavior to fit the most common use cases. Applications that requre a different setup must implement their own cluster.

func NewCluster 

func NewCluster(hosts ...string) *ClusterConfig

NewCluster generates a new config for the default cluster implementation.

func (*ClusterConfig) CreateSession 

func (cfg *ClusterConfig) CreateSession() (*Session, error)

CreateSession initializes the cluster based on this config and returns a session object that can be used to interact with the database.

type ColumnInfo 

type ColumnInfo struct {
	Keyspace string
	Table    string
	Name     string
	TypeInfo *TypeInfo
}

type Compressor 

type Compressor interface {
	Name() string
	Encode(data []byte) ([]byte, error)
	Decode(data []byte) ([]byte, error)
}

type Conn 

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

Conn is a single connection to a Cassandra node. It can be used to execute queries, but users are usually advised to use a more reliable, higher level API.

func Connect 

func Connect(addr string, cfg ConnConfig, cluster Cluster) (*Conn, error)

Connect establishes a connection to a Cassandra node. You must also call the Serve method before you can execute any queries.

func (*Conn) Address 

func (c *Conn) Address() string

func (*Conn) Close 

func (c *Conn) Close()

func (*Conn) Pick 

func (c *Conn) Pick(qry *Query) *Conn

func (*Conn) UseKeyspace 

func (c *Conn) UseKeyspace(keyspace string) error

type ConnConfig 

type ConnConfig struct {
	ProtoVersion  int
	CQLVersion    string
	Timeout       time.Duration
	NumStreams    int
	Compressor    Compressor
	Authenticator Authenticator
	Keepalive     time.Duration
}

type Consistency 

type Consistency int
const (
	Any Consistency = 1 + iota
	One
	Two
	Three
	Quorum
	All
	LocalQuorum
	EachQuorum
	Serial
	LocalSerial
)

func (Consistency) String 

func (c Consistency) String() string

type Error 

type Error struct {
	Code    int
	Message string
}

func (Error) Error 

func (e Error) Error() string

type Iter 

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

Iter represents an iterator that can be used to iterate over all rows that were returned by a query. The iterator might send additional queries to the database during the iteration if paging was enabled.

func (*Iter) Close 

func (iter *Iter) Close() error

Close closes the iterator and returns any errors that happened during the query or the iteration.

func (*Iter) Columns 

func (iter *Iter) Columns() []ColumnInfo

Columns returns the name and type of the selected columns.

func (*Iter) MapScan 

func (iter *Iter) MapScan(m map[string]interface{}) bool

MapScan takes a map[string]interface{} and populates it with a row That is returned from cassandra.

func (*Iter) Scan 

func (iter *Iter) Scan(dest ...interface{}) bool

Scan consumes the next row of the iterator and copies the columns of the current row into the values pointed at by dest. Use nil as a dest value to skip the corresponding column. Scan might send additional queries to the database to retrieve the next set of rows if paging was enabled.

Scan returns true if the row was successfully unmarshaled or false if the end of the result set was reached or if an error occurred. Close should be called afterwards to retrieve any potential errors.

func (*Iter) SliceMap 

func (iter *Iter) SliceMap() ([]map[string]interface{}, error)

SliceMap is a helper function to make the API easier to use returns the data from the query in the form of []map[string]interface{}

type MarshalError 

type MarshalError string

func (MarshalError) Error 

func (m MarshalError) Error() string

type Marshaler 

type Marshaler interface {
	MarshalCQL(info *TypeInfo) ([]byte, error)
}

Marshaler is the interface implemented by objects that can marshal themselves into values understood by Cassandra.

type Node 

type Node interface {
	Pick(qry *Query) *Conn
	Close()
}

type PasswordAuthenticator 

type PasswordAuthenticator struct {
	Username string
	Password string
}

func (PasswordAuthenticator) Challenge 

func (p PasswordAuthenticator) Challenge(req []byte) ([]byte, Authenticator, error)

func (PasswordAuthenticator) Success 

func (p PasswordAuthenticator) Success(data []byte) error

type Query 

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

Query represents a CQL statement that can be executed.

func (*Query) Consistency 

func (q *Query) Consistency(c Consistency) *Query

Consistency sets the consistency level for this query. If no consistency level have been set, the default consistency level of the cluster is used.

func (*Query) Exec 

func (q *Query) Exec() error

Exec executes the query without returning any rows.

func (*Query) Iter 

func (q *Query) Iter() *Iter

Iter executes the query and returns an iterator capable of iterating over all results.

func (*Query) PageSize 

func (q *Query) PageSize(n int) *Query

PageSize will tell the iterator to fetch the result in pages of size n. This is useful for iterating over large result sets, but setting the page size to low might decrease the performance. This feature is only available in Cassandra 2 and onwards.

func (*Query) Prefetch 

func (q *Query) Prefetch(p float64) *Query

SetPrefetch sets the default threshold for pre-fetching new pages. If there are only p*pageSize rows remaining, the next page will be requested automatically.

func (*Query) RetryPolicy 

func (q *Query) RetryPolicy(r RetryPolicy) *Query

RetryPolicy sets the policy to use when retrying the query.

func (*Query) Scan 

func (q *Query) Scan(dest ...interface{}) error

Scan executes the query, copies the columns of the first selected row into the values pointed at by dest and discards the rest. If no rows were selected, ErrNotFound is returned.

func (*Query) ScanCAS 

func (q *Query) ScanCAS(dest ...interface{}) (applied bool, err error)

ScanCAS executes a lightweight transaction (i.e. an UPDATE or INSERT statement containing an IF clause). If the transaction fails because the existing values did not match, the previos values will be stored in dest.

func (*Query) Trace 

func (q *Query) Trace(trace Tracer) *Query

Trace enables tracing of this query. Look at the documentation of the Tracer interface to learn more about tracing.

type RetryPolicy 

type RetryPolicy struct {
	NumRetries int //Number of times to retry a query
}

RetryPolicy represents the retry behavour for a query.

type RoundRobin 

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

func NewRoundRobin 

func NewRoundRobin() *RoundRobin

func (*RoundRobin) AddNode 

func (r *RoundRobin) AddNode(node Node)

func (*RoundRobin) Close 

func (r *RoundRobin) Close()

func (*RoundRobin) Pick 

func (r *RoundRobin) Pick(qry *Query) *Conn

func (*RoundRobin) RemoveNode 

func (r *RoundRobin) RemoveNode(node Node)

func (*RoundRobin) Size 

func (r *RoundRobin) Size() int

type Session 

type Session struct {
	Node Node
	// contains filtered or unexported fields
}

Session is the interface used by users to interact with the database.

It's safe for concurrent use by multiple goroutines and a typical usage scenario is to have one global session object to interact with the whole Cassandra cluster.

This type extends the Node interface by adding a convinient query builder and automatically sets a default consinstency level on all operations that do not have a consistency level set.

func NewSession 

func NewSession(c *clusterImpl) *Session

NewSession wraps an existing Node.

func (*Session) Close 

func (s *Session) Close()

Close closes all connections. The session is unusable after this operation.

func (*Session) ExecuteBatch 

func (s *Session) ExecuteBatch(batch *Batch) error

ExecuteBatch executes a batch operation and returns nil if successful otherwise an error is returned describing the failure.

func (*Session) NewBatch 

func (s *Session) NewBatch(typ BatchType) *Batch

NewBatch creates a new batch operation using defaults defined in the cluster

func (*Session) Query 

func (s *Session) Query(stmt string, values ...interface{}) *Query

Query generates a new query object for interacting with the database. Further details of the query may be tweaked using the resulting query value before the query is executed.

func (*Session) SetConsistency 

func (s *Session) SetConsistency(cons Consistency)

SetConsistency sets the default consistency level for this session. This setting can also be changed on a per-query basis and the default value is Quorum.

func (*Session) SetPageSize 

func (s *Session) SetPageSize(n int)

SetPageSize sets the default page size for this session. A value <= 0 will disable paging. This setting can also be changed on a per-query basis.

func (*Session) SetPrefetch 

func (s *Session) SetPrefetch(p float64)

SetPrefetch sets the default threshold for pre-fetching new pages. If there are only p*pageSize rows remaining, the next page will be requested automatically. This value can also be changed on a per-query basis and the default value is 0.25.

func (*Session) SetTrace 

func (s *Session) SetTrace(trace Tracer)

SetTrace sets the default tracer for this session. This setting can also be changed on a per-query basis.

type SnappyCompressor 

type SnappyCompressor struct{}

SnappyCompressor implements the Compressor interface and can be used to compress incoming and outgoing frames. The snappy compression algorithm aims for very high speeds and reasonable compression.

func (SnappyCompressor) Decode 

func (s SnappyCompressor) Decode(data []byte) ([]byte, error)

func (SnappyCompressor) Encode 

func (s SnappyCompressor) Encode(data []byte) ([]byte, error)

func (SnappyCompressor) Name 

func (s SnappyCompressor) Name() string

type Tracer 

type Tracer interface {
	Trace(traceId []byte)
}

Tracer is the interface implemented by query tracers. Tracers have the ability to obtain a detailed event log of all events that happened during the execution of a query from Cassandra. Gathering this information might be essential for debugging and optimizing queries, but this feature should not be used on production systems with very high load.

func NewTraceWriter 

func NewTraceWriter(session *Session, w io.Writer) Tracer

NewTraceWriter returns a simple Tracer implementation that outputs the event log in a textual format.

type Type 

type Type int

Type is the identifier of a Cassandra internal datatype. 

const (
	TypeCustom    Type = 0x0000
	TypeAscii     Type = 0x0001
	TypeBigInt    Type = 0x0002
	TypeBlob      Type = 0x0003
	TypeBoolean   Type = 0x0004
	TypeCounter   Type = 0x0005
	TypeDecimal   Type = 0x0006
	TypeDouble    Type = 0x0007
	TypeFloat     Type = 0x0008
	TypeInt       Type = 0x0009
	TypeTimestamp Type = 0x000B
	TypeUUID      Type = 0x000C
	TypeVarchar   Type = 0x000D
	TypeVarint    Type = 0x000E
	TypeTimeUUID  Type = 0x000F
	TypeInet      Type = 0x0010
	TypeList      Type = 0x0020
	TypeMap       Type = 0x0021
	TypeSet       Type = 0x0022
)

func (Type) String 

func (t Type) String() string

String returns the name of the identifier.

type TypeInfo 

type TypeInfo struct {
	Type   Type
	Key    *TypeInfo // only used for TypeMap
	Elem   *TypeInfo // only used for TypeMap, TypeList and TypeSet
	Custom string    // only used for TypeCostum
}

TypeInfo describes a Cassandra specific data type.

func (*TypeInfo) New 

func (t *TypeInfo) New() interface{}

New creates a pointer to an empty version of whatever type is referenced by the TypeInfo receiver

func (TypeInfo) String 

func (t TypeInfo) String() string

String returns a human readable name for the Cassandra datatype described by t.

type UUID 

type UUID [16]byte

func ParseUUID 

func ParseUUID(input string) (UUID, error)

ParseUUID parses a 32 digit hexadecimal number (that might contain hypens) represanting an UUID.

func RandomUUID 

func RandomUUID() (UUID, error)

RandomUUID generates a totally random UUID (version 4) as described in RFC 4122.

func TimeUUID 

func TimeUUID() UUID

TimeUUID generates a new time based UUID (version 1) using the current time as the timestamp.

func UUIDFromBytes 

func UUIDFromBytes(input []byte) (UUID, error)

UUIDFromBytes converts a raw byte slice to an UUID.

func UUIDFromTime 

func UUIDFromTime(aTime time.Time) UUID

UUIDFromTime generates a new time based UUID (version 1) as described in RFC 4122. This UUID contains the MAC address of the node that generated the UUID, the given timestamp and a sequence number.

func (UUID) Bytes 

func (u UUID) Bytes() []byte

Bytes returns the raw byte slice for this UUID. A UUID is always 128 bits (16 bytes) long.

func (UUID) Node 

func (u UUID) Node() []byte

Node extracts the MAC address of the node who generated this UUID. It will return nil if the UUID is not a time based UUID (version 1).

func (UUID) String 

func (u UUID) String() string

String returns the UUID in it's canonical form, a 32 digit hexadecimal number in the form of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

func (UUID) Time 

func (u UUID) Time() time.Time

Time is like Timestamp, except that it returns a time.Time.

func (UUID) Timestamp 

func (u UUID) Timestamp() int64

Timestamp extracts the timestamp information from a time based UUID (version 1).

func (UUID) Variant 

func (u UUID) Variant() int

Variant returns the variant of this UUID. This package will only generate UUIDs in the IETF variant.

func (UUID) Version 

func (u UUID) Version() int

Version extracts the version of this UUID variant. The RFC 4122 describes five kinds of UUIDs.

type UnmarshalError 

type UnmarshalError string

func (UnmarshalError) Error 

func (m UnmarshalError) Error() string

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalCQL(info *TypeInfo, data []byte) error
}

Unmarshaler is the interface implemented by objects that can unmarshal a Cassandra specific description of themselves.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.