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.
Index ¶
- Constants
- Variables
- func Marshal(info *TypeInfo, value interface{}) ([]byte, error)
- func NewErrProtocol(format string, args ...interface{}) error
- func Unmarshal(info *TypeInfo, data []byte, value interface{}) error
- type Authenticator
- type Batch
- type BatchEntry
- type BatchType
- type ClusterConfig
- type ColumnInfo
- type Compressor
- type Conn
- type ConnConfig
- type ConnectionPool
- type Consistency
- type DiscoveryConfig
- type ErrProtocol
- type Error
- type HostInfo
- type Iter
- type MarshalError
- type Marshaler
- type NewPoolFunc
- type Node
- type PasswordAuthenticator
- type Query
- func (q *Query) Attempts() int
- func (q *Query) Bind(v ...interface{}) *Query
- func (q *Query) Consistency(c Consistency) *Query
- func (q *Query) Exec() error
- func (q *Query) Iter() *Iter
- func (q *Query) Latency() int64
- func (q *Query) PageSize(n int) *Query
- func (q *Query) Prefetch(p float64) *Query
- func (q *Query) RetryPolicy(r RetryPolicy) *Query
- func (q *Query) Scan(dest ...interface{}) error
- func (q *Query) ScanCAS(dest ...interface{}) (applied bool, err error)
- func (q *Query) Trace(trace Tracer) *Query
- type QueryInfo
- type RequestErrAlreadyExists
- type RequestErrReadTimeout
- type RequestErrUnavailable
- type RequestErrUnprepared
- type RequestErrWriteTimeout
- type RequestError
- type RetryPolicy
- type RoundRobin
- type RowData
- type Session
- func (s *Session) Bind(stmt string, b func(q *QueryInfo) ([]interface{}, error)) *Query
- func (s *Session) Close()
- func (s *Session) Closed() bool
- func (s *Session) ExecuteBatch(batch *Batch) error
- func (s *Session) NewBatch(typ BatchType) *Batch
- func (s *Session) Query(stmt string, values ...interface{}) *Query
- func (s *Session) SetConsistency(cons Consistency)
- func (s *Session) SetPageSize(n int)
- func (s *Session) SetPrefetch(p float64)
- func (s *Session) SetTrace(trace Tracer)
- type SimplePool
- type SnappyCompressor
- type Tracer
- type Type
- type TypeInfo
- type UUID
- type UnmarshalError
- type Unmarshaler
Constants ¶
const ( VariantNCSCompat = 0 VariantIETF = 2 VariantMicrosoft = 6 VariantFuture = 7 )
const BatchSizeMaximum = 65535
BatchSizeMaximum is the maximum number of statements a batch operation can have. This limit is set by cassandra and could change in the future.
Variables ¶
var ( ErrNoHosts = errors.New("no hosts provided") ErrNoConnectionsStarted = errors.New("no connections were made when creating the session") ErrHostQueryFailed = errors.New("unable to populate Hosts") )
var ( ErrNotFound = errors.New("not found") ErrUnsupported = errors.New("feature not supported") ErrTooManyStmts = errors.New("too many statements") ErrUseStmt = errors.New("use statements aren't supported. Please see https://github.com/gocql/gocql for explaination.") ErrSessionClosed = errors.New("session has been closed") ErrNoConnections = errors.New("no connections available") )
var ConsistencyNames = []string{ 0: "default", Any: "any", One: "one", Two: "two", Three: "three", Quorum: "quorum", All: "all", LocalQuorum: "localquorum", EachQuorum: "eachquorum", Serial: "serial", LocalSerial: "localserial", LocalOne: "localone", }
var (
ErrQueryArgLength = errors.New("query argument length mismatch")
)
Functions ¶
func Marshal ¶
Marshal returns the CQL encoding of the value for the Cassandra internal type described by the info parameter.
func NewErrProtocol ¶
Types ¶
type Authenticator ¶
type Batch ¶
type Batch struct { Type BatchType Entries []BatchEntry Cons Consistency // contains filtered or unexported fields }
func (*Batch) Bind ¶
Bind adds the query to the batch operation and correlates it with a binding callback that will be invoked when the batch is executed. The binding callback allows the application to define which query argument values will be marshalled as part of the batch execution.
func (*Batch) Latency ¶
Latency returns the average number of nanoseconds to execute a single attempt of the batch.
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{} // contains filtered or unexported fields }
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) Port int // 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) 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) ConnPoolType NewPoolFunc // The function used to create the connection pool for the session (default: NewSimplePool) DiscoverHosts bool // If set, gocql will attempt to automatically discover other members of the Cassandra cluster (default: false) MaxPreparedStmts int // Sets the maximum cache size for prepared statements globally for gocql (default: 1000) Discovery DiscoveryConfig }
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 Compressor ¶
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, pool ConnectionPool) (*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) UseKeyspace ¶
type ConnConfig ¶
type ConnConfig struct { ProtoVersion int CQLVersion string Timeout time.Duration NumStreams int Compressor Compressor Authenticator Authenticator Keepalive time.Duration }
type ConnectionPool ¶
type ConnectionPool interface { Pick(*Query) *Conn Size() int HandleError(*Conn, error, bool) Close() SetHosts(host []HostInfo) }
ConnectionPool represents the interface gocql will use to work with a collection of connections.
Purpose ¶
The connection pool in gocql opens and closes connections as well as selects an available connection for gocql to execute a query against. The pool is also respnsible for handling connection errors that are caught by the connection experiencing the error.
A connection pool should make a copy of the variables used from the ClusterConfig provided to the pool upon creation. ClusterConfig is a pointer and can be modified after the creation of the pool. This can lead to issues with variables being modified outside the expectations of the ConnectionPool type.
Example of Single Connection Pool:
type SingleConnection struct { conn *Conn cfg *ClusterConfig } func NewSingleConnection(cfg *ClusterConfig) ConnectionPool { addr := strings.TrimSpace(cfg.Hosts[0]) if strings.Index(addr, ":") < 0 { addr = fmt.Sprintf("%s:%d", addr, cfg.Port) } connCfg := ConnConfig{ ProtoVersion: cfg.ProtoVersion, CQLVersion: cfg.CQLVersion, Timeout: cfg.Timeout, NumStreams: cfg.NumStreams, Compressor: cfg.Compressor, Authenticator: cfg.Authenticator, Keepalive: cfg.SocketKeepalive, } pool := SingleConnection{cfg:cfg} pool.conn = Connect(addr,connCfg,pool) return &pool } func (s *SingleConnection) HandleError(conn *Conn, err error, closed bool) { if closed { connCfg := ConnConfig{ ProtoVersion: cfg.ProtoVersion, CQLVersion: cfg.CQLVersion, Timeout: cfg.Timeout, NumStreams: cfg.NumStreams, Compressor: cfg.Compressor, Authenticator: cfg.Authenticator, Keepalive: cfg.SocketKeepalive, } s.conn = Connect(conn.Address(),connCfg,s) } } func (s *SingleConnection) Pick(qry *Query) *Conn { if s.conn.isClosed { return nil } return s.conn } func (s *SingleConnection) Size() int { return 1 } func (s *SingleConnection) Close() { s.conn.Close() }
This is a very simple example of a type that exposes the connection pool interface. To assign this type as the connection pool to use you would assign it to the ClusterConfig like so:
cluster := NewCluster("127.0.0.1") cluster.ConnPoolType = NewSingleConnection ... session, err := cluster.CreateSession()
To see a more complete example of a ConnectionPool implementation please see the SimplePool type.
func NewSimplePool ¶
func NewSimplePool(cfg *ClusterConfig) ConnectionPool
NewSimplePool is the function used by gocql to create the simple connection pool. This is the default if no other pool type is specified.
type Consistency ¶
type Consistency int
const ( Any Consistency = 1 + iota One Two Three Quorum All LocalQuorum EachQuorum Serial LocalSerial LocalOne )
func (Consistency) String ¶
func (c Consistency) String() string
type DiscoveryConfig ¶
type DiscoveryConfig struct { // If not empty will filter all discoverred hosts to a single Data Centre (default: "") DcFilter string // If not empty will filter all discoverred hosts to a single Rack (default: "") RackFilter string // The interval to check for new hosts (default: 30s) Sleep time.Duration }
To enable periodic node discovery enable DiscoverHosts in ClusterConfig
type ErrProtocol ¶
type ErrProtocol struct {
// contains filtered or unexported fields
}
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 ¶
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 ¶
MapScan takes a map[string]interface{} and populates it with a row That is returned from cassandra.
func (*Iter) Scan ¶
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.
type MarshalError ¶
type MarshalError string
func (MarshalError) Error ¶
func (m MarshalError) Error() string
type Marshaler ¶
Marshaler is the interface implemented by objects that can marshal themselves into values understood by Cassandra.
type NewPoolFunc ¶
type NewPoolFunc func(*ClusterConfig) ConnectionPool
NewPoolFunc is the type used by ClusterConfig to create a pool of a specific type.
type PasswordAuthenticator ¶
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) Bind ¶
Bind sets query arguments of query. This can also be used to rebind new query arguments to an existing query instance.
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) Iter ¶
Iter executes the query and returns an iterator capable of iterating over all results.
func (*Query) PageSize ¶
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 ¶
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 ¶
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.
type QueryInfo ¶
type QueryInfo struct { Id []byte Args []ColumnInfo Rval []ColumnInfo }
QueryInfo represents the meta data associated with a prepared CQL statement.
type RequestErrAlreadyExists ¶
type RequestErrReadTimeout ¶
type RequestErrReadTimeout struct { Consistency Consistency Received int BlockFor int DataPresent byte // contains filtered or unexported fields }
type RequestErrUnavailable ¶
type RequestErrUnavailable struct { // contains filtered or unexported fields }
type RequestErrUnprepared ¶
type RequestErrUnprepared struct { StatementId []byte // contains filtered or unexported fields }
type RequestErrWriteTimeout ¶
type RequestErrWriteTimeout struct { Consistency Consistency Received int BlockFor int WriteType string // contains filtered or unexported fields }
type RequestError ¶
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 { Pool ConnectionPool // 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(p ConnectionPool, c ClusterConfig) *Session
NewSession wraps an existing Node.
func (*Session) Bind ¶
Bind generates a new query object based on the query statement passed in. The query is automatically prepared if it has not previously been executed. The binding callback allows the application to define which query argument values will be marshalled as part of the query execution. During execution, the meta data of the prepared query will be routed to the binding callback, which is responsible for producing the query argument values.
func (*Session) Close ¶
func (s *Session) Close()
Close closes all connections. The session is unusable after this operation.
func (*Session) ExecuteBatch ¶
ExecuteBatch executes a batch operation and returns nil if successful otherwise an error is returned describing the failure.
func (*Session) NewBatch ¶
NewBatch creates a new batch operation using defaults defined in the cluster
func (*Session) 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. Query is automatically prepared if it has not previously been 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 ¶
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 ¶
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.
type SimplePool ¶
type SimplePool struct {
// contains filtered or unexported fields
}
SimplePool is the current implementation of the connection pool inside gocql. This pool is meant to be a simple default used by gocql so users can get up and running quickly.
func (*SimplePool) Close ¶
func (c *SimplePool) Close()
Close kills the pool and all associated connections.
func (*SimplePool) HandleError ¶
func (c *SimplePool) HandleError(conn *Conn, err error, closed bool)
HandleError is called by a Connection object to report to the pool an error has occured. Logic is then executed within the pool to clean up the erroroneous connection and try to top off the pool.
func (*SimplePool) Pick ¶
func (c *SimplePool) Pick(qry *Query) *Conn
Pick selects a connection to be used by the query.
func (*SimplePool) SetHosts ¶
func (c *SimplePool) SetHosts(hosts []HostInfo)
func (*SimplePool) Size ¶
func (p *SimplePool) Size() int
Size returns the number of connections currently active in the pool
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) 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.
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 )
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.
type UUID ¶
type UUID [16]byte
func ParseUUID ¶
ParseUUID parses a 32 digit hexadecimal number (that might contain hypens) represanting an UUID.
func RandomUUID ¶
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 ¶
UUIDFromBytes converts a raw byte slice to an UUID.
func UUIDFromTime ¶
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 ¶
Bytes returns the raw byte slice for this UUID. A UUID is always 128 bits (16 bytes) long.
func (UUID) Node ¶
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 ¶
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) Timestamp ¶
Timestamp extracts the timestamp information from a time based UUID (version 1).
type UnmarshalError ¶
type UnmarshalError string
func (UnmarshalError) Error ¶
func (m UnmarshalError) Error() string
type Unmarshaler ¶
Unmarshaler is the interface implemented by objects that can unmarshal a Cassandra specific description of themselves.