README
¶
gocql
Package gocql implements a fast and robust Cassandra client for the Go programming language.
Project Website: https://gocql.github.io/
API documentation: https://godoc.org/github.com/gocql/gocql
Discussions: https://groups.google.com/forum/#!forum/gocql
Supported Versions
The following matrix shows the versions of Go and Cassandra that are tested with the integration test suite as part of the CI build:
Go/Cassandra | 2.1.x | 2.2.x | 3.x.x |
---|---|---|---|
1.15 | yes | yes | yes |
1.16 | yes | yes | yes |
Gocql has been tested in production against many different versions of Cassandra. Due to limits in our CI setup we only test against the latest 3 major releases, which coincide with the official support from the Apache project.
Sunsetting Model
In general, the gocql team will focus on supporting the current and previous versions of Go. gocql may still work with older versions of Go, but official support for these versions will have been sunset.
Installation
go get github.com/gocql/gocql
Features
- Modern Cassandra client using the native transport
- Automatic type conversions between Cassandra and Go
- Support for all common types including sets, lists and maps
- Custom types can implement a
Marshaler
andUnmarshaler
interface - Strict type conversions 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 n concurrent queries (whereby n is the limit set by the protocol version the client chooses to use)
- Optional automatic discovery of nodes
- Policy based connection pool with token aware and round-robin policy implementations
- Support for password authentication
- Iteration over paged results with configurable page size
- Support for TLS/SSL
- Optional frame compression (using snappy)
- Automatic query preparation
- Support for query tracing
- Support for Cassandra 2.1+ binary protocol version 3
- Support for up to 32768 streams
- Support for tuple types
- Support for client side timestamps by default
- Support for UDTs via a custom marshaller or struct tags
- Support for Cassandra 3.0+ binary protocol version 4
- An API to access the schema metadata of a given keyspace
Performance
While the driver strives to be highly performant, there are cases where it is difficult to test and verify. The driver is built with maintainability and code readability in mind first and then performance and features, as such every now and then performance may degrade, if this occurs please report and issue and it will be looked at and remedied. The only time the driver copies data from its read buffer is when it Unmarshal's data into supplied types.
Some tips for getting more performance from the driver:
- Use the TokenAware policy
- Use many goroutines when doing inserts, the driver is asynchronous but provides a synchronous API, it can execute many queries concurrently
- Tune query page size
- Reading data from the network to unmarshal will incur a large amount of allocations, this can adversely affect the garbage collector, tune
GOGC
- Close iterators after use to recycle byte buffers
Important Default Keyspace Changes
gocql no longer supports executing "use " statements to simplify the library. The user still has the ability to define the default keyspace for connections but now the keyspace can only be defined before a session is created. Queries can still access keyspaces by indicating the keyspace in the query:
SELECT * FROM example2.table;
Example of correct usage:
cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
cluster.Keyspace = "example"
...
session, err := cluster.CreateSession()
Example of incorrect usage:
cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
cluster.Keyspace = "example"
...
session, err := cluster.CreateSession()
if err = session.Query("use example2").Exec(); err != nil {
log.Fatal(err)
}
This will result in an err being returned from the session.Query line as the user is trying to execute a "use" statement.
Example
Data Binding
There are various ways to bind application level data structures to CQL statements:
- You can write the data binding by hand, as outlined in the Tweet example. This provides you with the greatest flexibility, but it does mean that you need to keep your application code in sync with your Cassandra schema.
- You can dynamically marshal an entire query result into an
[]map[string]interface{}
using theSliceMap()
API. This returns a slice of row maps keyed by CQL column names. This method requires no special interaction with the gocql API, but it does require your application to be able to deal with a key value view of your data. - As a refinement on the
SliceMap()
API you can also callMapScan()
which returnsmap[string]interface{}
instances in a row by row fashion. - The
Bind()
API provides a client app with a low level mechanism to introspect query meta data and extract appropriate field values from application level data structures. - The gocqlx package is an idiomatic extension to gocql that provides usability features. With gocqlx you can bind the query parameters from maps and structs, use named query parameters (:identifier) and scan the query results into structs and slices. It comes with a fluent and flexible CQL query builder that supports full CQL spec, including BATCH statements and custom functions.
- Building on top of the gocql driver, cqlr adds the ability to auto-bind a CQL iterator to a struct or to bind a struct to an INSERT statement.
- Another external project that layers on top of gocql is cqlc which generates gocql compliant code from your Cassandra schema so that you can write type safe CQL statements in Go with a natural query syntax.
- gocassa is an external project that layers on top of gocql to provide convenient query building and data binding.
- gocqltable provides an ORM-style convenience layer to make CRUD operations with gocql easier.
Ecosystem
The following community maintained tools are known to integrate with gocql:
- gocqlx is a gocql extension that automates data binding, adds named queries support, provides flexible query builders and plays well with gocql.
- journey is a migration tool with Cassandra support.
- negronicql is gocql middleware for Negroni.
- cqlr adds the ability to auto-bind a CQL iterator to a struct or to bind a struct to an INSERT statement.
- 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.
- gocassa provides query building, adds data binding, and provides easy-to-use "recipe" tables for common query use-cases.
- gocqltable is a wrapper around gocql that aims to simplify common operations.
- gockle provides simple, mockable interfaces that wrap gocql types
- scylladb is a fast Apache Cassandra-compatible NoSQL database
- go-cql-driver is an CQL driver conforming to the built-in database/sql interface. It is good for simple use cases where the database/sql interface is wanted. The CQL driver is a wrapper around this project.
Other Projects
- 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 traditionaldatabase/sql
API. Use this package instead.
SEO
For some reason, when you Google golang cassandra
, this project doesn't feature very highly in the result list. But if you Google go cassandra
, then we're a bit higher up the list. So this is note to try to convince Google that golang is an alias for Go.
License
Copyright (c) 2012-2016 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.
Connecting to the cluster ¶
Pass a list of initial node IP addresses to NewCluster to create a new cluster configuration:
cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
Port can be specified as part of the address, the above is equivalent to:
cluster := gocql.NewCluster("192.168.1.1:9042", "192.168.1.2:9042", "192.168.1.3:9042")
It is recommended to use the value set in the Cassandra config for broadcast_address or listen_address, an IP address not a domain name. This is because events from Cassandra will use the configured IP address, which is used to index connected hosts. If the domain name specified resolves to more than 1 IP address then the driver may connect multiple times to the same host, and will not mark the node being down or up from events.
Then you can customize more options (see ClusterConfig):
cluster.Keyspace = "example" cluster.Consistency = gocql.Quorum cluster.ProtoVersion = 4
The driver tries to automatically detect the protocol version to use if not set, but you might want to set the protocol version explicitly, as it's not defined which version will be used in certain situations (for example during upgrade of the cluster when some of the nodes support different set of protocol versions than other nodes).
When ready, create a session from the configuration. Don't forget to Close the session once you are done with it:
session, err := cluster.CreateSession() if err != nil { return err } defer session.Close()
Authentication ¶
CQL protocol uses a SASL-based authentication mechanism and so consists of an exchange of server challenges and client response pairs. The details of the exchanged messages depend on the authenticator used.
To use authentication, set ClusterConfig.Authenticator or ClusterConfig.AuthProvider.
PasswordAuthenticator is provided to use for username/password authentication:
cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3") cluster.Authenticator = gocql.PasswordAuthenticator{ Username: "user", Password: "password" } session, err := cluster.CreateSession() if err != nil { return err } defer session.Close()
Transport layer security ¶
It is possible to secure traffic between the client and server with TLS.
To use TLS, set the ClusterConfig.SslOpts field. SslOptions embeds *tls.Config so you can set that directly. There are also helpers to load keys/certificates from files.
Warning: Due to historical reasons, the SslOptions is insecure by default, so you need to set EnableHostVerification to true if no Config is set. Most users should set SslOptions.Config to a *tls.Config. SslOptions and Config.InsecureSkipVerify interact as follows:
Config.InsecureSkipVerify | EnableHostVerification | Result Config is nil | false | do not verify host Config is nil | true | verify host false | false | verify host true | false | do not verify host false | true | verify host true | true | verify host
For example:
cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3") cluster.SslOpts = &gocql.SslOptions{ EnableHostVerification: true, } session, err := cluster.CreateSession() if err != nil { return err } defer session.Close()
Executing queries ¶
Create queries with Session.Query. Query values must not be reused between different executions and must not be modified after starting execution of the query.
To execute a query without reading results, use Query.Exec:
err := session.Query(`INSERT INTO tweet (timeline, id, text) VALUES (?, ?, ?)`, "me", gocql.TimeUUID(), "hello world").WithContext(ctx).Exec()
Single row can be read by calling Query.Scan:
err := session.Query(`SELECT id, text FROM tweet WHERE timeline = ? LIMIT 1`, "me").WithContext(ctx).Consistency(gocql.One).Scan(&id, &text)
Multiple rows can be read using Iter.Scanner:
scanner := session.Query(`SELECT id, text FROM tweet WHERE timeline = ?`, "me").WithContext(ctx).Iter().Scanner() for scanner.Next() { var ( id gocql.UUID text string ) err = scanner.Scan(&id, &text) if err != nil { log.Fatal(err) } fmt.Println("Tweet:", id, text) } // scanner.Err() closes the iterator, so scanner nor iter should be used afterwards. if err := scanner.Err(); err != nil { log.Fatal(err) }
See Example for complete example.
Prepared statements ¶
The driver automatically prepares DML queries (SELECT/INSERT/UPDATE/DELETE/BATCH statements) and maintains a cache of prepared statements. CQL protocol does not support preparing other query types.
When using CQL protocol >= 4, it is possible to use gocql.UnsetValue as the bound value of a column. This will cause the database to ignore writing the column. The main advantage is the ability to keep the same prepared statement even when you don't want to update some fields, where before you needed to make another prepared statement.
Executing multiple queries concurrently ¶
Session is safe to use from multiple goroutines, so to execute multiple concurrent queries, just execute them from several worker goroutines. Gocql provides synchronously-looking API (as recommended for Go APIs) and the queries are executed asynchronously at the protocol level.
results := make(chan error, 2) go func() { results <- session.Query(`INSERT INTO tweet (timeline, id, text) VALUES (?, ?, ?)`, "me", gocql.TimeUUID(), "hello world 1").Exec() }() go func() { results <- session.Query(`INSERT INTO tweet (timeline, id, text) VALUES (?, ?, ?)`, "me", gocql.TimeUUID(), "hello world 2").Exec() }()
Nulls ¶
Null values are are unmarshalled as zero value of the type. If you need to distinguish for example between text column being null and empty string, you can unmarshal into *string variable instead of string.
var text *string err := scanner.Scan(&text) if err != nil { // handle error } if text != nil { // not null } else { // null }
See Example_nulls for full example.
Reusing slices ¶
The driver reuses backing memory of slices when unmarshalling. This is an optimization so that a buffer does not need to be allocated for every processed row. However, you need to be careful when storing the slices to other memory structures.
scanner := session.Query(`SELECT myints FROM table WHERE pk = ?`, "key").WithContext(ctx).Iter().Scanner() var myInts []int for scanner.Next() { // This scan reuses backing store of myInts for each row. err = scanner.Scan(&myInts) if err != nil { log.Fatal(err) } }
When you want to save the data for later use, pass a new slice every time. A common pattern is to declare the slice variable within the scanner loop:
scanner := session.Query(`SELECT myints FROM table WHERE pk = ?`, "key").WithContext(ctx).Iter().Scanner() for scanner.Next() { var myInts []int // This scan always gets pointer to fresh myInts slice, so does not reuse memory. err = scanner.Scan(&myInts) if err != nil { log.Fatal(err) } }
Paging ¶
The driver supports paging of results with automatic prefetch, see ClusterConfig.PageSize, Session.SetPrefetch, Query.PageSize, and Query.Prefetch.
It is also possible to control the paging manually with Query.PageState (this disables automatic prefetch). Manual paging is useful if you want to store the page state externally, for example in a URL to allow users browse pages in a result. You might want to sign/encrypt the paging state when exposing it externally since it contains data from primary keys.
Paging state is specific to the CQL protocol version and the exact query used. It is meant as opaque state that should not be modified. If you send paging state from different query or protocol version, then the behaviour is not defined (you might get unexpected results or an error from the server). For example, do not send paging state returned by node using protocol version 3 to a node using protocol version 4. Also, when using protocol version 4, paging state between Cassandra 2.2 and 3.0 is incompatible (https://issues.apache.org/jira/browse/CASSANDRA-10880).
The driver does not check whether the paging state is from the same protocol version/statement. You might want to validate yourself as this could be a problem if you store paging state externally. For example, if you store paging state in a URL, the URLs might become broken when you upgrade your cluster.
Call Query.PageState(nil) to fetch just the first page of the query results. Pass the page state returned by Iter.PageState to Query.PageState of a subsequent query to get the next page. If the length of slice returned by Iter.PageState is zero, there are no more pages available (or an error occurred).
Using too low values of PageSize will negatively affect performance, a value below 100 is probably too low. While Cassandra returns exactly PageSize items (except for last page) in a page currently, the protocol authors explicitly reserved the right to return smaller or larger amount of items in a page for performance reasons, so don't rely on the page having the exact count of items.
See Example_paging for an example of manual paging.
Dynamic list of columns ¶
There are certain situations when you don't know the list of columns in advance, mainly when the query is supplied by the user. Iter.Columns, Iter.RowData, Iter.MapScan and Iter.SliceMap can be used to handle this case.
See Example_dynamicColumns.
Batches ¶
The CQL protocol supports sending batches of DML statements (INSERT/UPDATE/DELETE) and so does gocql. Use Session.NewBatch to create a new batch and then fill-in details of individual queries. Then execute the batch with Session.ExecuteBatch.
Logged batches ensure atomicity, either all or none of the operations in the batch will succeed, but they have overhead to ensure this property. Unlogged batches don't have the overhead of logged batches, but don't guarantee atomicity. Updates of counters are handled specially by Cassandra so batches of counter updates have to use CounterBatch type. A counter batch can only contain statements to update counters.
For unlogged batches it is recommended to send only single-partition batches (i.e. all statements in the batch should involve only a single partition). Multi-partition batch needs to be split by the coordinator node and re-sent to correct nodes. With single-partition batches you can send the batch directly to the node for the partition without incurring the additional network hop.
It is also possible to pass entire BEGIN BATCH .. APPLY BATCH statement to Query.Exec. There are differences how those are executed. BEGIN BATCH statement passed to Query.Exec is prepared as a whole in a single statement. Session.ExecuteBatch prepares individual statements in the batch. If you have variable-length batches using the same statement, using Session.ExecuteBatch is more efficient.
See Example_batch for an example.
Lightweight transactions ¶
Query.ScanCAS or Query.MapScanCAS can be used to execute a single-statement lightweight transaction (an INSERT/UPDATE .. IF statement) and reading its result. See example for Query.MapScanCAS.
Multiple-statement lightweight transactions can be executed as a logged batch that contains at least one conditional statement. All the conditions must return true for the batch to be applied. You can use Session.ExecuteBatchCAS and Session.MapExecuteBatchCAS when executing the batch to learn about the result of the LWT. See example for Session.MapExecuteBatchCAS.
Retries and speculative execution ¶
Queries can be marked as idempotent. Marking the query as idempotent tells the driver that the query can be executed multiple times without affecting its result. Non-idempotent queries are not eligible for retrying nor speculative execution.
Idempotent queries are retried in case of errors based on the configured RetryPolicy.
Queries can be retried even before they fail by setting a SpeculativeExecutionPolicy. The policy can cause the driver to retry on a different node if the query is taking longer than a specified delay even before the driver receives an error or timeout from the server. When a query is speculatively executed, the original execution is still executing. The two parallel executions of the query race to return a result, the first received result will be returned.
User-defined types ¶
UDTs can be mapped (un)marshaled from/to map[string]interface{} a Go struct (or a type implementing UDTUnmarshaler, UDTMarshaler, Unmarshaler or Marshaler interfaces).
For structs, cql tag can be used to specify the CQL field name to be mapped to a struct field:
type MyUDT struct { FieldA int32 `cql:"a"` FieldB string `cql:"b"` }
See Example_userDefinedTypesMap, Example_userDefinedTypesStruct, ExampleUDTMarshaler, ExampleUDTUnmarshaler.
Metrics and tracing ¶
It is possible to provide observer implementations that could be used to gather metrics:
- QueryObserver for monitoring individual queries. - BatchObserver for monitoring batch queries. - ConnectObserver for monitoring new connections from the driver to the database. - FrameHeaderObserver for monitoring individual protocol frames.
CQL protocol also supports tracing of queries. When enabled, the database will write information about internal events that happened during execution of the query. You can use Query.Trace to request tracing and receive the session ID that the database used to store the trace information in system_traces.sessions and system_traces.events tables. NewTraceWriter returns an implementation of Tracer that writes the events to a writer. Gathering trace information might be essential for debugging and optimizing queries, but writing traces has overhead, so this feature should not be used on production systems with very high load unless you know what you are doing.
Example (DynamicColumns) ¶
Example_dynamicColumns demonstrates how to handle dynamic column list.
Output:
Example (MarshalerUnmarshaler) ¶
Example_marshalerUnmarshaler demonstrates how to implement a Marshaler and Unmarshaler.
Output:
Example (Nulls) ¶
Example_nulls demonstrates how to distinguish between null and zero value when needed.
Null values are unmarshalled as zero value of the type. If you need to distinguish for example between text column being null and empty string, you can unmarshal into *string field.
Output:
Example (Paging) ¶
Example_paging demonstrates how to manually fetch pages and use page state.
See also package documentation about paging.
Output:
Example (UserDefinedTypesMap) ¶
Example_userDefinedTypesMap demonstrates how to work with user-defined types as maps. See also Example_userDefinedTypesStruct and examples for UDTMarshaler and UDTUnmarshaler if you want to map to structs.
Output:
Example (UserDefinedTypesStruct) ¶
Example_userDefinedTypesStruct demonstrates how to work with user-defined types as structs. See also examples for UDTMarshaler and UDTUnmarshaler if you need more control/better performance.
Output:
Index ¶
- Constants
- Variables
- func JoinHostPort(addr string, port int) string
- func LookupIP(host string) ([]net.IP, error)
- func Marshal(info TypeInfo, value interface{}) ([]byte, error)
- func NamedValue(name string, value interface{}) interface{}
- func NewErrProtocol(format string, args ...interface{}) error
- func NonLocalReplicasFallback() func(policy *tokenAwareHostPolicy)
- func ShuffleReplicas() func(*tokenAwareHostPolicy)
- func SingleHostReadyPolicy(p HostSelectionPolicy) *singleHostReadyPolicy
- func TupleColumnName(c string, n int) string
- func Unmarshal(info TypeInfo, data []byte, value interface{}) error
- type AddressTranslator
- type AddressTranslatorFunc
- type AggregateMetadata
- type Authenticator
- type Batch
- func (b *Batch) AddAttempts(i int, host *HostInfo)
- func (b *Batch) AddLatency(l int64, host *HostInfo)
- func (b *Batch) Attempts() int
- func (b *Batch) Bind(stmt string, bind func(q *QueryInfo) ([]interface{}, error))
- func (*Batch) Cancel()
- func (b *Batch) Context() context.Context
- func (b *Batch) DefaultTimestamp(enable bool) *Batch
- func (b *Batch) GetConsistency() Consistency
- func (b *Batch) GetRoutingKey() ([]byte, error)
- func (b *Batch) IsIdempotent() bool
- func (b *Batch) Keyspace() string
- func (b *Batch) Latency() int64
- func (b *Batch) Observer(observer BatchObserver) *Batch
- func (b *Batch) Query(stmt string, args ...interface{})
- func (b *Batch) RetryPolicy(r RetryPolicy) *Batch
- func (b *Batch) SerialConsistency(cons SerialConsistency) *Batch
- func (b *Batch) SetConsistency(c Consistency)
- func (b *Batch) Size() int
- func (b *Batch) SpeculativeExecutionPolicy(sp SpeculativeExecutionPolicy) *Batch
- func (b *Batch) WithContext(ctx context.Context) *Batch
- func (b *Batch) WithTimestamp(timestamp int64) *Batch
- type BatchEntry
- type BatchObserver
- type BatchType
- type ClusterConfig
- type CollectionType
- type ColumnIndexMetadata
- type ColumnInfo
- type ColumnKind
- type ColumnMetadata
- type ColumnOrder
- type Compressor
- type Conn
- func (c *Conn) Address() string
- func (c *Conn) AvailableStreams() int
- func (c *Conn) Close()
- func (c *Conn) Closed() bool
- func (c *Conn) Pick(qry *Query) *Conn
- func (c *Conn) Read(p []byte) (n int, err error)
- func (c *Conn) UseKeyspace(keyspace string) error
- func (c *Conn) Write(p []byte) (n int, err error)
- type ConnConfig
- type ConnErrorHandler
- type ConnectObserver
- type Consistency
- type ConstantReconnectionPolicy
- type ConvictionPolicy
- type Dialer
- type DowngradingConsistencyRetryPolicy
- type Duration
- type ErrProtocol
- type Error
- type ErrorMap
- type ExecutableQuery
- type ExponentialBackoffRetryPolicy
- type ExponentialReconnectionPolicy
- type FrameHeaderObserver
- type FunctionMetadata
- type HostFilter
- type HostFilterFunc
- type HostInfo
- func (h *HostInfo) BroadcastAddress() net.IP
- func (h *HostInfo) ClusterName() string
- func (h *HostInfo) ConnectAddress() net.IP
- func (h *HostInfo) DSEVersion() string
- func (h *HostInfo) DataCenter() string
- func (h *HostInfo) Equal(host *HostInfo) bool
- func (h *HostInfo) Graph() bool
- func (h *HostInfo) HostID() string
- func (h *HostInfo) HostnameAndPort() string
- func (h *HostInfo) IsUp() bool
- func (h *HostInfo) ListenAddress() net.IP
- func (h *HostInfo) Partitioner() string
- func (h *HostInfo) Peer() net.IP
- func (h *HostInfo) Port() int
- func (h *HostInfo) PreferredIP() net.IP
- func (h *HostInfo) RPCAddress() net.IP
- func (h *HostInfo) Rack() string
- func (h *HostInfo) SetConnectAddress(address net.IP) *HostInfo
- func (h *HostInfo) State() nodeState
- func (h *HostInfo) String() string
- func (h *HostInfo) Tokens() []string
- func (h *HostInfo) Version() cassVersion
- func (h *HostInfo) WorkLoad() string
- type HostSelectionPolicy
- type HostStateNotifier
- type Iter
- func (iter *Iter) Close() error
- func (iter *Iter) Columns() []ColumnInfo
- func (iter *Iter) GetCustomPayload() map[string][]byte
- func (iter *Iter) Host() *HostInfo
- func (iter *Iter) MapScan(m map[string]interface{}) bool
- func (iter *Iter) NumRows() int
- func (iter *Iter) PageState() []byte
- func (iter *Iter) RowData() (RowData, error)
- func (iter *Iter) Scan(dest ...interface{}) bool
- func (iter *Iter) Scanner() Scanner
- func (iter *Iter) SliceMap() ([]map[string]interface{}, error)
- func (iter *Iter) Warnings() []string
- func (iter *Iter) WillSwitchPage() bool
- type KeyspaceMetadata
- type KeyspaceUpdateEvent
- type MarshalError
- type Marshaler
- type MaterializedViewMetadata
- type NativeType
- type NextHost
- type NonSpeculativeExecution
- type ObservedBatch
- type ObservedConnect
- type ObservedFrameHeader
- type ObservedQuery
- type PasswordAuthenticator
- type PoolConfig
- type Query
- func (q *Query) AddAttempts(i int, host *HostInfo)
- func (q *Query) AddLatency(l int64, host *HostInfo)
- func (q *Query) Attempts() int
- func (q *Query) Bind(v ...interface{}) *Query
- func (q *Query) Cancel()
- func (q *Query) Consistency(c Consistency) *Query
- func (q *Query) Context() context.Context
- func (q *Query) CustomPayload(customPayload map[string][]byte) *Query
- func (q *Query) DefaultTimestamp(enable bool) *Query
- func (q *Query) Exec() error
- func (q *Query) GetConsistency() Consistency
- func (q *Query) GetRoutingKey() ([]byte, error)
- func (q *Query) Idempotent(value bool) *Query
- func (q *Query) IsIdempotent() bool
- func (q *Query) Iter() *Iter
- func (q *Query) Keyspace() string
- func (q *Query) Latency() int64
- func (q *Query) MapScan(m map[string]interface{}) error
- func (q *Query) MapScanCAS(dest map[string]interface{}) (applied bool, err error)
- func (q *Query) NoSkipMetadata() *Query
- func (q *Query) Observer(observer QueryObserver) *Query
- func (q *Query) PageSize(n int) *Query
- func (q *Query) PageState(state []byte) *Query
- func (q *Query) Prefetch(p float64) *Query
- func (q *Query) Release()
- func (q *Query) RetryPolicy(r RetryPolicy) *Query
- func (q *Query) RoutingKey(routingKey []byte) *Query
- func (q *Query) Scan(dest ...interface{}) error
- func (q *Query) ScanCAS(dest ...interface{}) (applied bool, err error)
- func (q *Query) SerialConsistency(cons SerialConsistency) *Query
- func (q *Query) SetConsistency(c Consistency)
- func (q *Query) SetSpeculativeExecutionPolicy(sp SpeculativeExecutionPolicy) *Query
- func (q Query) Statement() string
- func (q Query) String() string
- func (q *Query) Trace(trace Tracer) *Query
- func (q *Query) WithContext(ctx context.Context) *Query
- func (q *Query) WithTimestamp(timestamp int64) *Query
- type QueryInfo
- type QueryObserver
- type ReadyPolicy
- type ReconnectionPolicy
- type RequestErrAlreadyExists
- type RequestErrCDCWriteFailure
- type RequestErrFunctionFailure
- type RequestErrReadFailure
- type RequestErrReadTimeout
- type RequestErrUnavailable
- type RequestErrUnprepared
- type RequestErrWriteFailure
- type RequestErrWriteTimeout
- type RequestError
- type RetryPolicy
- type RetryType
- type RetryableQuery
- type RowData
- type Scanner
- type SelectedHost
- type SerialConsistency
- type Session
- func (s *Session) AwaitSchemaAgreement(ctx context.Context) error
- 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) ExecuteBatchCAS(batch *Batch, dest ...interface{}) (applied bool, iter *Iter, err error)
- func (s *Session) KeyspaceMetadata(keyspace string) (*KeyspaceMetadata, error)
- func (s *Session) MapExecuteBatchCAS(batch *Batch, dest map[string]interface{}) (applied bool, iter *Iter, err 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 SetHosts
- type SetPartitioner
- type SimpleConvictionPolicy
- type SimpleRetryPolicy
- type SimpleSpeculativeExecution
- type SnappyCompressor
- type SpeculativeExecutionPolicy
- type SslOptions
- type StdLogger
- type TableMetadata
- type Tracer
- type TupleTypeInfo
- type Type
- type TypeInfo
- type UDTField
- type UDTMarshaler
- type UDTTypeInfo
- type UDTUnmarshaler
- type UUID
- func MaxTimeUUID(t time.Time) UUID
- func MinTimeUUID(t time.Time) UUID
- func ParseUUID(input string) (UUID, error)
- func RandomUUID() (UUID, error)
- func TimeUUID() UUID
- func TimeUUIDWith(t int64, clock uint32, node []byte) UUID
- func UUIDFromBytes(input []byte) (UUID, error)
- func UUIDFromTime(t time.Time) UUID
- func (u UUID) Bytes() []byte
- func (u UUID) Clock() uint32
- func (u UUID) MarshalJSON() ([]byte, error)
- func (u UUID) MarshalText() ([]byte, error)
- func (u UUID) Node() []byte
- func (u UUID) String() string
- func (u UUID) Time() time.Time
- func (u UUID) Timestamp() int64
- func (u *UUID) UnmarshalJSON(data []byte) error
- func (u *UUID) UnmarshalText(text []byte) (err error)
- func (u UUID) Variant() int
- func (u UUID) Version() int
- type UnmarshalError
- type Unmarshaler
- type UserTypeMetadata
- type ViewMetadata
Examples ¶
Constants ¶
const ( NodeUp nodeState = iota NodeDown )
const ( DEFAULT_KEY_ALIAS = "key" DEFAULT_COLUMN_ALIAS = "column" DEFAULT_VALUE_ALIAS = "value" )
default alias values
const ( REVERSED_TYPE = "org.apache.cassandra.db.marshal.ReversedType" COMPOSITE_TYPE = "org.apache.cassandra.db.marshal.CompositeType" COLLECTION_TYPE = "org.apache.cassandra.db.marshal.ColumnToCollectionType" LIST_TYPE = "org.apache.cassandra.db.marshal.ListType" SET_TYPE = "org.apache.cassandra.db.marshal.SetType" MAP_TYPE = "org.apache.cassandra.db.marshal.MapType" )
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 ( ErrQueryArgLength = errors.New("gocql: query argument length mismatch") ErrTimeoutNoResponse = errors.New("gocql: no response received from cassandra within timeout period") ErrTooManyTimeouts = errors.New("gocql: too many query timeouts on the connection") ErrConnectionClosed = errors.New("gocql: connection closed waiting for response") ErrNoStreams = errors.New("gocql: no streams available on connection") )
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 explanation.") ErrSessionClosed = errors.New("session has been closed") ErrNoConnections = errors.New("gocql: no hosts available in the pool") ErrNoKeyspace = errors.New("no keyspace provided") ErrKeyspaceDoesNotExist = errors.New("keyspace does not exist") ErrNoMetadata = errors.New("no metadata available") )
var (
ErrFrameTooBig = errors.New("frame length is bigger than the maximum allowed")
)
var ErrUnknownRetryType = errors.New("unknown retry type returned by retry policy")
ErrUnknownRetryType is returned if the retry policy returns a retry type unknown to the query executor.
var (
)var TimeoutLimit int64 = 0
If not zero, how many timeouts we will allow to occur before the connection is closed and restarted. This is to prevent a single query timeout from killing a connection which may be serving more queries just fine. Default is 0, should not be changed concurrently with queries.
Deprecated.
var UnsetValue = unsetColumn{}
UnsetValue represents a value used in a query binding that will be ignored by Cassandra.
By setting a field to the unset value Cassandra will ignore the write completely. The main advantage is the ability to keep the same prepared statement even when you don't want to update some fields, where before you needed to make another prepared statement.
UnsetValue is only available when using the version 4 of the protocol.
Functions ¶
func JoinHostPort ¶
JoinHostPort is a utility to return an address string that can be used by `gocql.Conn` to form a connection with a host.
func Marshal ¶
Marshal returns the CQL encoding of the value for the Cassandra internal type described by the info parameter.
nil is serialized as CQL null. If value implements Marshaler, its MarshalCQL method is called to marshal the data. If value is a pointer, the pointed-to value is marshaled.
Supported conversions are as follows, other type combinations may be added in the future:
CQL type | Go type (value) | Note varchar, ascii, blob, text | string, []byte | boolean | bool | tinyint, smallint, int | integer types | tinyint, smallint, int | string | formatted as base 10 number bigint, counter | integer types | bigint, counter | big.Int | bigint, counter | string | formatted as base 10 number float | float32 | double | float64 | decimal | inf.Dec | time | int64 | nanoseconds since start of day time | time.Duration | duration since start of day timestamp | int64 | milliseconds since Unix epoch timestamp | time.Time | list, set | slice, array | list, set | map[X]struct{} | map | map[X]Y | uuid, timeuuid | gocql.UUID | uuid, timeuuid | [16]byte | raw UUID bytes uuid, timeuuid | []byte | raw UUID bytes, length must be 16 bytes uuid, timeuuid | string | hex representation, see ParseUUID varint | integer types | varint | big.Int | varint | string | value of number in decimal notation inet | net.IP | inet | string | IPv4 or IPv6 address string tuple | slice, array | tuple | struct | fields are marshaled in order of declaration user-defined type | gocql.UDTMarshaler | MarshalUDT is called user-defined type | map[string]interface{} | user-defined type | struct | struct fields' cql tags are used for column names date | int64 | milliseconds since Unix epoch to start of day (in UTC) date | time.Time | start of day (in UTC) date | string | parsed using "2006-01-02" format duration | int64 | duration in nanoseconds duration | time.Duration | duration | gocql.Duration | duration | string | parsed with time.ParseDuration
func NamedValue ¶
func NamedValue(name string, value interface{}) interface{}
NamedValue produce a value which will bind to the named parameter in a query
func NewErrProtocol ¶
func NonLocalReplicasFallback ¶
func NonLocalReplicasFallback() func(policy *tokenAwareHostPolicy)
NonLocalReplicasFallback enables fallback to replicas that are not considered local.
TokenAwareHostPolicy used with DCAwareHostPolicy fallback first selects replicas by partition key in local DC, then falls back to other nodes in the local DC. Enabling NonLocalReplicasFallback causes TokenAwareHostPolicy to first select replicas by partition key in local DC, then replicas by partition key in remote DCs and fall back to other nodes in local DC.
func ShuffleReplicas ¶
func ShuffleReplicas() func(*tokenAwareHostPolicy)
func SingleHostReadyPolicy ¶
func SingleHostReadyPolicy(p HostSelectionPolicy) *singleHostReadyPolicy
SingleHostReadyPolicy wraps a HostSelectionPolicy and returns Ready after a single host has been added via HostUp
func TupleColumnName ¶
TupeColumnName will return the column name of a tuple value in a column named c at index n. It should be used if a specific element within a tuple is needed to be extracted from a map returned from SliceMap or MapScan.
func Unmarshal ¶
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.
If value implements Unmarshaler, it's UnmarshalCQL method is called to unmarshal the data. If value is a pointer to pointer, it is set to nil if the CQL value is null. Otherwise, nulls are unmarshalled as zero value.
Supported conversions are as follows, other type combinations may be added in the future:
CQL type | Go type (value) | Note varchar, ascii, blob, text | *string | varchar, ascii, blob, text | *[]byte | non-nil buffer is reused bool | *bool | tinyint, smallint, int, bigint, counter | *integer types | tinyint, smallint, int, bigint, counter | *big.Int | tinyint, smallint, int, bigint, counter | *string | formatted as base 10 number float | *float32 | double | *float64 | decimal | *inf.Dec | time | *int64 | nanoseconds since start of day time | *time.Duration | timestamp | *int64 | milliseconds since Unix epoch timestamp | *time.Time | list, set | *slice, *array | map | *map[X]Y | uuid, timeuuid | *string | see UUID.String uuid, timeuuid | *[]byte | raw UUID bytes uuid, timeuuid | *gocql.UUID | timeuuid | *time.Time | timestamp of the UUID inet | *net.IP | inet | *string | IPv4 or IPv6 address string tuple | *slice, *array | tuple | *struct | struct fields are set in order of declaration user-defined types | gocql.UDTUnmarshaler | UnmarshalUDT is called user-defined types | *map[string]interface{} | user-defined types | *struct | cql tag is used to determine field name date | *time.Time | time of beginning of the day (in UTC) date | *string | formatted with 2006-01-02 format duration | *gocql.Duration |
Types ¶
type AddressTranslator ¶
type AddressTranslator interface { // Translate will translate the provided address and/or port to another // address and/or port. If no translation is possible, Translate will return the // address and port provided to it. Translate(addr net.IP, port int) (net.IP, int) }
AddressTranslator provides a way to translate node addresses (and ports) that are discovered or received as a node event. This can be useful in an ec2 environment, for instance, to translate public IPs to private IPs.
func IdentityTranslator ¶
func IdentityTranslator() AddressTranslator
IdentityTranslator will do nothing but return what it was provided. It is essentially a no-op.
type AddressTranslatorFunc ¶
type AggregateMetadata ¶
type AggregateMetadata struct { Keyspace string Name string ArgumentTypes []TypeInfo FinalFunc FunctionMetadata InitCond string ReturnType TypeInfo StateFunc FunctionMetadata StateType TypeInfo // contains filtered or unexported fields }
AggregateMetadata holds metadata for aggregate constructs
type Authenticator ¶
type Batch ¶
type Batch struct { Type BatchType Entries []BatchEntry Cons Consistency CustomPayload map[string][]byte // contains filtered or unexported fields }
func NewBatch ¶
NewBatch creates a new batch operation without defaults from the cluster
Deprecated: use session.NewBatch instead
func (*Batch) AddAttempts ¶
func (*Batch) AddLatency ¶
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) Cancel ¶
func (*Batch) Cancel()
Deprecate: does nothing, cancel the context passed to WithContext
func (*Batch) DefaultTimestamp ¶
DefaultTimestamp will enable the with default timestamp flag on the query. If enable, this will replace the server side assigned timestamp as default timestamp. Note that a timestamp in the query itself will still override this timestamp. This is entirely optional.
Only available on protocol >= 3
func (*Batch) GetConsistency ¶
func (b *Batch) GetConsistency() Consistency
GetConsistency returns the currently configured consistency level for the batch operation.
func (*Batch) GetRoutingKey ¶
func (*Batch) IsIdempotent ¶
func (*Batch) Latency ¶
Latency returns the average number of nanoseconds to execute a single attempt of the batch.
func (*Batch) Observer ¶
func (b *Batch) Observer(observer BatchObserver) *Batch
Observer enables batch-level observer on this batch. The provided observer will be called every time this batched query is executed.
func (*Batch) RetryPolicy ¶
func (b *Batch) RetryPolicy(r RetryPolicy) *Batch
RetryPolicy sets the retry policy to use when executing the batch operation
func (*Batch) SerialConsistency ¶
func (b *Batch) SerialConsistency(cons SerialConsistency) *Batch
SerialConsistency sets the consistency level for the serial phase of conditional updates. That consistency can only be either SERIAL or LOCAL_SERIAL and if not present, it defaults to SERIAL. This option will be ignored for anything else that a conditional update/insert.
Only available for protocol 3 and above
func (*Batch) SetConsistency ¶
func (b *Batch) SetConsistency(c Consistency)
SetConsistency sets the currently configured consistency level for the batch operation.
func (*Batch) Size ¶
Size returns the number of batch statements to be executed by the batch operation.
func (*Batch) SpeculativeExecutionPolicy ¶
func (b *Batch) SpeculativeExecutionPolicy(sp SpeculativeExecutionPolicy) *Batch
func (*Batch) WithContext ¶
WithContext returns a shallow copy of b with its context set to ctx.
The provided context controls the entire lifetime of executing a query, queries will be canceled and return once the context is canceled.
func (*Batch) WithTimestamp ¶
WithTimestamp will enable the with default timestamp flag on the query like DefaultTimestamp does. But also allows to define value for timestamp. It works the same way as USING TIMESTAMP in the query itself, but should not break prepared query optimization.
Only available on protocol >= 3
type BatchEntry ¶
type BatchObserver ¶
type BatchObserver interface { // ObserveBatch gets called on every batch query to cassandra. // It also gets called once for each query in a batch. // It doesn't get called if there is no query because the session is closed or there are no connections available. // The error reported only shows query errors, i.e. if a SELECT is valid but finds no matches it will be nil. // Unlike QueryObserver.ObserveQuery it does no reporting on rows read. ObserveBatch(context.Context, ObservedBatch) }
BatchObserver is the interface implemented by batch observers / stat collectors.
type ClusterConfig ¶
type ClusterConfig struct { // addresses for the initial connections. It is recommended to use the value set in // the Cassandra config for broadcast_address or listen_address, an IP address not // a domain name. This is because events from Cassandra will use the configured IP // address, which is used to index connected hosts. If the domain name specified // resolves to more than 1 IP address then the driver may connect multiple times to // the same host, and will not mark the node being down or up from events. Hosts []string CQLVersion string // CQL version (default: 3.0.0) // ProtoVersion sets the version of the native protocol to use, this will // enable features in the driver for specific protocol versions, generally this // should be set to a known version (2,3,4) for the cluster being connected to. // // If it is 0 or unset (the default) then the driver will attempt to discover the // highest supported protocol for the cluster. In clusters with nodes of different // versions the protocol selected is not defined (ie, it can be any of the supported in the cluster) ProtoVersion int Timeout time.Duration // connection timeout (default: 600ms) ConnectTimeout time.Duration // initial connection timeout, used during initial dial to server (default: 600ms) Port int // port (default: 9042) Keyspace string // initial keyspace (optional) NumConns int // number of connections per host (default: 2) Consistency Consistency // default consistency level (default: Quorum) Compressor Compressor // compression algorithm (default: nil) Authenticator Authenticator // authenticator (default: nil) AuthProvider func(h *HostInfo) (Authenticator, error) // an authenticator factory. Can be used to create alternative authenticators (default: nil) RetryPolicy RetryPolicy // Default retry policy to use for queries (default: 0) ConvictionPolicy ConvictionPolicy // Decide whether to mark host as down based on the error and host info (default: SimpleConvictionPolicy) ReconnectionPolicy ReconnectionPolicy // Default reconnection policy to use for reconnecting before trying to mark host as down (default: see below) SocketKeepalive time.Duration // The keepalive period to use, enabled if > 0 (default: 0) MaxPreparedStmts int // Sets the maximum cache size for prepared statements globally for gocql (default: 1000) MaxRoutingKeyInfo int // Sets the maximum cache size for query info about statements for each session (default: 1000) PageSize int // Default page size to use for created sessions (default: 5000) SerialConsistency SerialConsistency // Sets the consistency for the serial part of queries, values can be either SERIAL or LOCAL_SERIAL (default: unset) SslOpts *SslOptions DefaultTimestamp bool // Sends a client side timestamp for all requests which overrides the timestamp at which it arrives at the server. (default: true, only enabled for protocol 3 and above) // PoolConfig configures the underlying connection pool, allowing the // configuration of host selection and connection selection policies. PoolConfig PoolConfig // If not zero, gocql attempt to reconnect known DOWN nodes in every ReconnectInterval. ReconnectInterval time.Duration // The maximum amount of time to wait for schema agreement in a cluster after // receiving a schema change frame. (default: 60s) MaxWaitSchemaAgreement time.Duration // HostFilter will filter all incoming events for host, any which don't pass // the filter will be ignored. If set will take precedence over any options set // via Discovery HostFilter HostFilter // AddressTranslator will translate addresses found on peer discovery and/or // node change events. AddressTranslator AddressTranslator // If IgnorePeerAddr is true and the address in system.peers does not match // the supplied host by either initial hosts or discovered via events then the // host will be replaced with the supplied address. // // For example if an event comes in with host=10.0.0.1 but when looking up that // address in system.local or system.peers returns 127.0.0.1, the peer will be // set to 10.0.0.1 which is what will be used to connect to. IgnorePeerAddr bool // If DisableInitialHostLookup then the driver will not attempt to get host info // from the system.peers table, this will mean that the driver will connect to // hosts supplied and will not attempt to lookup the hosts information, this will // mean that data_centre, rack and token information will not be available and as // such host filtering and token aware query routing will not be available. DisableInitialHostLookup bool // Configure events the driver will register for Events struct { // disable registering for status events (node up/down) DisableNodeStatusEvents bool // disable registering for topology events (node added/removed/moved) DisableTopologyEvents bool // disable registering for schema events (keyspace/table/function removed/created/updated) DisableSchemaEvents bool } // DisableSkipMetadata will override the internal result metadata cache so that the driver does not // send skip_metadata for queries, this means that the result will always contain // the metadata to parse the rows and will not reuse the metadata from the prepared // statement. // // See https://issues.apache.org/jira/browse/CASSANDRA-10786 DisableSkipMetadata bool // QueryObserver will set the provided query observer on all queries created from this session. // Use it to collect metrics / stats from queries by providing an implementation of QueryObserver. QueryObserver QueryObserver // BatchObserver will set the provided batch observer on all queries created from this session. // Use it to collect metrics / stats from batch queries by providing an implementation of BatchObserver. BatchObserver BatchObserver // ConnectObserver will set the provided connect observer on all queries // created from this session. ConnectObserver ConnectObserver // FrameHeaderObserver will set the provided frame header observer on all frames' headers created from this session. // Use it to collect metrics / stats from frames by providing an implementation of FrameHeaderObserver. FrameHeaderObserver FrameHeaderObserver // Default idempotence for queries DefaultIdempotence bool // The time to wait for frames before flushing the frames connection to Cassandra. // Can help reduce syscall overhead by making less calls to write. Set to 0 to // disable. // // (default: 200 microseconds) WriteCoalesceWaitTime time.Duration // Dialer will be used to establish all connections created for this Cluster. // If not provided, a default dialer configured with ConnectTimeout will be used. Dialer Dialer // contains filtered or unexported fields }
ClusterConfig is a struct to configure the default cluster implementation of gocql. It has a variety of attributes that can be used to modify the behavior to fit the most common use cases. Applications that require 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.
The supplied hosts are used to initially connect to the cluster then the rest of the ring will be automatically discovered. It is recommended to use the value set in the Cassandra config for broadcast_address or listen_address, an IP address not a domain name. This is because events from Cassandra will use the configured IP address, which is used to index connected hosts. If the domain name specified resolves to more than 1 IP address then the driver may connect multiple times to the same host, and will not mark the node being down or up from events.
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 CollectionType ¶
type CollectionType struct { NativeType Key TypeInfo // only used for TypeMap Elem TypeInfo // only used for TypeMap, TypeList and TypeSet }
func (CollectionType) New ¶
func (t CollectionType) New() interface{}
func (CollectionType) String ¶
func (c CollectionType) String() string
type ColumnIndexMetadata ¶
type ColumnInfo ¶
func (ColumnInfo) String ¶
func (c ColumnInfo) String() string
type ColumnKind ¶
type ColumnKind int
const ( ColumnUnkownKind ColumnKind = iota ColumnPartitionKey ColumnClusteringKey ColumnRegular ColumnCompact ColumnStatic )
func (ColumnKind) String ¶
func (c ColumnKind) String() string
func (*ColumnKind) UnmarshalCQL ¶
func (c *ColumnKind) UnmarshalCQL(typ TypeInfo, p []byte) error
type ColumnMetadata ¶
type ColumnMetadata struct { Keyspace string Table string Name string ComponentIndex int Kind ColumnKind Validator string Type TypeInfo ClusteringOrder string Order ColumnOrder Index ColumnIndexMetadata }
schema metadata for a column
type ColumnOrder ¶
type ColumnOrder bool
the ordering of the column with regard to its comparator
const ( ASC ColumnOrder = false DESC = true )
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 (*Conn) AvailableStreams ¶
func (*Conn) UseKeyspace ¶
type ConnConfig ¶
type ConnConfig struct { ProtoVersion int CQLVersion string Timeout time.Duration ConnectTimeout time.Duration Dialer Dialer Compressor Compressor Authenticator Authenticator AuthProvider func(h *HostInfo) (Authenticator, error) Keepalive time.Duration // contains filtered or unexported fields }
type ConnErrorHandler ¶
type ConnectObserver ¶
type ConnectObserver interface { // ObserveConnect gets called when a new connection to cassandra is made. ObserveConnect(ObservedConnect) }
ConnectObserver is the interface implemented by connect observers / stat collectors.
type Consistency ¶
type Consistency uint16
const ( Any Consistency = 0x00 One Consistency = 0x01 Two Consistency = 0x02 Three Consistency = 0x03 Quorum Consistency = 0x04 All Consistency = 0x05 LocalQuorum Consistency = 0x06 EachQuorum Consistency = 0x07 LocalOne Consistency = 0x0A )
func MustParseConsistency ¶
func MustParseConsistency(s string) (Consistency, error)
MustParseConsistency is the same as ParseConsistency except it returns an error (never). It is kept here since breaking changes are not good. DEPRECATED: use ParseConsistency if you want a panic on parse error.
func ParseConsistency ¶
func ParseConsistency(s string) Consistency
func ParseConsistencyWrapper ¶
func ParseConsistencyWrapper(s string) (consistency Consistency, err error)
ParseConsistencyWrapper wraps gocql.ParseConsistency to provide an err return instead of a panic
func (Consistency) MarshalText ¶
func (c Consistency) MarshalText() (text []byte, err error)
func (Consistency) String ¶
func (c Consistency) String() string
func (*Consistency) UnmarshalText ¶
func (c *Consistency) UnmarshalText(text []byte) error
type ConstantReconnectionPolicy ¶
ConstantReconnectionPolicy has simple logic for returning a fixed reconnection interval.
Examples of usage:
cluster.ReconnectionPolicy = &gocql.ConstantReconnectionPolicy{MaxRetries: 10, Interval: 8 * time.Second}
func (*ConstantReconnectionPolicy) GetInterval ¶
func (c *ConstantReconnectionPolicy) GetInterval(currentRetry int) time.Duration
func (*ConstantReconnectionPolicy) GetMaxRetries ¶
func (c *ConstantReconnectionPolicy) GetMaxRetries() int
type ConvictionPolicy ¶
type ConvictionPolicy interface { // Implementations should return `true` if the host should be convicted, `false` otherwise. AddFailure(error error, host *HostInfo) bool //Implementations should clear out any convictions or state regarding the host. Reset(host *HostInfo) }
ConvictionPolicy interface is used by gocql to determine if a host should be marked as DOWN based on the error and host info
type DowngradingConsistencyRetryPolicy ¶
type DowngradingConsistencyRetryPolicy struct {
ConsistencyLevelsToTry []Consistency
}
func (*DowngradingConsistencyRetryPolicy) Attempt ¶
func (d *DowngradingConsistencyRetryPolicy) Attempt(q RetryableQuery) bool
func (*DowngradingConsistencyRetryPolicy) GetRetryType ¶
func (d *DowngradingConsistencyRetryPolicy) GetRetryType(err error) RetryType
type ErrProtocol ¶
type ErrProtocol struct {
// contains filtered or unexported fields
}
type ExecutableQuery ¶
type ExecutableQuery interface { GetRoutingKey() ([]byte, error) Keyspace() string IsIdempotent() bool RetryableQuery // contains filtered or unexported methods }
type ExponentialBackoffRetryPolicy ¶
ExponentialBackoffRetryPolicy sleeps between attempts
func (*ExponentialBackoffRetryPolicy) Attempt ¶
func (e *ExponentialBackoffRetryPolicy) Attempt(q RetryableQuery) bool
func (*ExponentialBackoffRetryPolicy) GetRetryType ¶
func (e *ExponentialBackoffRetryPolicy) GetRetryType(err error) RetryType
type ExponentialReconnectionPolicy ¶
type ExponentialReconnectionPolicy struct { MaxRetries int InitialInterval time.Duration MaxInterval time.Duration }
ExponentialReconnectionPolicy returns a growing reconnection interval.
func (*ExponentialReconnectionPolicy) GetInterval ¶
func (e *ExponentialReconnectionPolicy) GetInterval(currentRetry int) time.Duration
func (*ExponentialReconnectionPolicy) GetMaxRetries ¶
func (e *ExponentialReconnectionPolicy) GetMaxRetries() int
type FrameHeaderObserver ¶
type FrameHeaderObserver interface { // ObserveFrameHeader gets called on every received frame header. ObserveFrameHeader(context.Context, ObservedFrameHeader) }
FrameHeaderObserver is the interface implemented by frame observers / stat collectors.
Experimental, this interface and use may change
type FunctionMetadata ¶
type FunctionMetadata struct { Keyspace string Name string ArgumentTypes []TypeInfo ArgumentNames []string Body string CalledOnNullInput bool Language string ReturnType TypeInfo }
FunctionMetadata holds metadata for function constructs
type HostFilter ¶
type HostFilter interface { // Called when a new host is discovered, returning true will cause the host // to be added to the pools. Accept(host *HostInfo) bool }
HostFilter interface is used when a host is discovered via server sent events.
func DataCentreHostFilter ¶
func DataCentreHostFilter(dataCentre string) HostFilter
DataCentreHostFilter filters all hosts such that they are in the same data centre as the supplied data centre.
func DenyAllFilter ¶
func DenyAllFilter() HostFilter
func WhiteListHostFilter ¶
func WhiteListHostFilter(hosts ...string) HostFilter
WhiteListHostFilter filters incoming hosts by checking that their address is in the initial hosts whitelist.
type HostFilterFunc ¶
HostFilterFunc converts a func(host HostInfo) bool into a HostFilter
func (HostFilterFunc) Accept ¶
func (fn HostFilterFunc) Accept(host *HostInfo) bool
type HostInfo ¶
type HostInfo struct {
// contains filtered or unexported fields
}
func (*HostInfo) BroadcastAddress ¶
func (*HostInfo) ClusterName ¶
func (*HostInfo) ConnectAddress ¶
Returns the address that should be used to connect to the host. If you wish to override this, use an AddressTranslator or use a HostFilter to SetConnectAddress()
func (*HostInfo) DSEVersion ¶
func (*HostInfo) DataCenter ¶
func (*HostInfo) HostnameAndPort ¶
func (*HostInfo) ListenAddress ¶
func (*HostInfo) Partitioner ¶
func (*HostInfo) PreferredIP ¶
func (*HostInfo) RPCAddress ¶
type HostSelectionPolicy ¶
type HostSelectionPolicy interface { HostStateNotifier SetPartitioner KeyspaceChanged(KeyspaceUpdateEvent) Init(*Session) IsLocal(host *HostInfo) bool // Pick returns an iteration function over selected hosts. // Multiple attempts of a single query execution won't call the returned NextHost function concurrently, // so it's safe to have internal state without additional synchronization as long as every call to Pick returns // a different instance of NextHost. Pick(ExecutableQuery) NextHost }
HostSelectionPolicy is an interface for selecting the most appropriate host to execute a given query.
func DCAwareRoundRobinPolicy ¶
func DCAwareRoundRobinPolicy(localDC string) HostSelectionPolicy
DCAwareRoundRobinPolicy is a host selection policies which will prioritize and return hosts which are in the local datacentre before returning hosts in all other datercentres
func HostPoolHostPolicy ¶
func HostPoolHostPolicy(hp hostpool.HostPool) HostSelectionPolicy
HostPoolHostPolicy is a host policy which uses the bitly/go-hostpool library to distribute queries between hosts and prevent sending queries to unresponsive hosts. When creating the host pool that is passed to the policy use an empty slice of hosts as the hostpool will be populated later by gocql. See below for examples of usage:
// Create host selection policy using a simple host pool cluster.PoolConfig.HostSelectionPolicy = HostPoolHostPolicy(hostpool.New(nil)) // Create host selection policy using an epsilon greedy pool cluster.PoolConfig.HostSelectionPolicy = HostPoolHostPolicy( hostpool.NewEpsilonGreedy(nil, 0, &hostpool.LinearEpsilonValueCalculator{}), )
func RoundRobinHostPolicy ¶
func RoundRobinHostPolicy() HostSelectionPolicy
RoundRobinHostPolicy is a round-robin load balancing policy, where each host is tried sequentially for each query.
func TokenAwareHostPolicy ¶
func TokenAwareHostPolicy(fallback HostSelectionPolicy, opts ...func(*tokenAwareHostPolicy)) HostSelectionPolicy
TokenAwareHostPolicy is a token aware host selection policy, where hosts are selected based on the partition key, so queries are sent to the host which owns the partition. Fallback is used when routing information is not available.
type HostStateNotifier ¶
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) GetCustomPayload ¶
GetCustomPayload returns any parsed custom payload results if given in the response from Cassandra. Note that the result is not a copy.
This additional feature of CQL Protocol v4 allows additional results and query information to be returned by custom QueryHandlers running in your C* cluster. See https://datastax.github.io/java-driver/manual/custom_payloads/
func (*Iter) MapScan ¶
MapScan takes a map[string]interface{} and populates it with a row that is returned from cassandra.
Each call to MapScan() must be called with a new map object. During the call to MapScan() any pointers in the existing map are replaced with non pointer types before the call returns
iter := session.Query(`SELECT * FROM mytable`).Iter() for { // New map each iteration row := make(map[string]interface{}) if !iter.MapScan(row) { break } // Do things with row if fullname, ok := row["fullname"]; ok { fmt.Printf("Full Name: %s\n", fullname) } }
You can also pass pointers in the map before each call
var fullName FullName // Implements gocql.Unmarshaler and gocql.Marshaler interfaces var address net.IP var age int iter := session.Query(`SELECT * FROM scan_map_table`).Iter() for { // New map each iteration row := map[string]interface{}{ "fullname": &fullName, "age": &age, "address": &address, } if !iter.MapScan(row) { break } fmt.Printf("First: %s Age: %d Address: %q\n", fullName.FirstName, age, address) }
func (*Iter) NumRows ¶
NumRows returns the number of rows in this pagination, it will update when new pages are fetched, it is not the value of the total number of rows this iter will return unless there is only a single page returned.
func (*Iter) PageState ¶
PageState return the current paging state for a query which can be used for subsequent queries to resume paging this point.
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.
func (*Iter) Scanner ¶
Scanner returns a row Scanner which provides an interface to scan rows in a manner which is similar to database/sql. The iter should NOT be used again after calling this method.
func (*Iter) SliceMap ¶
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{}
func (*Iter) Warnings ¶
Warnings returns any warnings generated if given in the response from Cassandra.
This is only available starting with CQL Protocol v4.
func (*Iter) WillSwitchPage ¶
WillSwitchPage detects if iterator reached end of current page and the next page is available.
type KeyspaceMetadata ¶
type KeyspaceMetadata struct { Name string DurableWrites bool StrategyClass string StrategyOptions map[string]interface{} Tables map[string]*TableMetadata Functions map[string]*FunctionMetadata Aggregates map[string]*AggregateMetadata // Deprecated: use the MaterializedViews field for views and UserTypes field for udts instead. Views map[string]*ViewMetadata MaterializedViews map[string]*MaterializedViewMetadata UserTypes map[string]*UserTypeMetadata }
schema metadata for a keyspace
type KeyspaceUpdateEvent ¶
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 MaterializedViewMetadata ¶
type MaterializedViewMetadata struct { Keyspace string Name string BaseTableId UUID BaseTable *TableMetadata BloomFilterFpChance float64 Caching map[string]string Comment string Compaction map[string]string Compression map[string]string CrcCheckChance float64 DcLocalReadRepairChance float64 DefaultTimeToLive int Extensions map[string]string GcGraceSeconds int Id UUID IncludeAllColumns bool MaxIndexInterval int MemtableFlushPeriodInMs int MinIndexInterval int ReadRepairChance float64 SpeculativeRetry string // contains filtered or unexported fields }
MaterializedViewMetadata holds the metadata for materialized views.
type NativeType ¶
type NativeType struct {
// contains filtered or unexported fields
}
func NewNativeType ¶
func NewNativeType(proto byte, typ Type, custom string) NativeType
func (NativeType) Custom ¶
func (s NativeType) Custom() string
func (NativeType) New ¶
func (t NativeType) New() interface{}
func (NativeType) String ¶
func (s NativeType) String() string
func (NativeType) Type ¶
func (s NativeType) Type() Type
func (NativeType) Version ¶
func (s NativeType) Version() byte
type NextHost ¶
type NextHost func() SelectedHost
NextHost is an iteration function over picked hosts
type NonSpeculativeExecution ¶
type NonSpeculativeExecution struct{}
func (NonSpeculativeExecution) Attempts ¶
func (sp NonSpeculativeExecution) Attempts() int
func (NonSpeculativeExecution) Delay ¶
func (sp NonSpeculativeExecution) Delay() time.Duration
type ObservedBatch ¶
type ObservedBatch struct { Keyspace string Statements []string Start time.Time // time immediately before the batch query was called End time.Time // time immediately after the batch query returned // Host is the informations about the host that performed the batch Host *HostInfo // Err is the error in the batch query. // It only tracks network errors or errors of bad cassandra syntax, in particular selects with no match return nil error Err error // The metrics per this host Metrics *hostMetrics // Attempt is the index of attempt at executing this query. // The first attempt is number zero and any retries have non-zero attempt number. Attempt int }
type ObservedConnect ¶
type ObservedFrameHeader ¶
type ObservedFrameHeader struct { Version protoVersion Flags byte Stream int16 Opcode frameOp Length int32 // StartHeader is the time we started reading the frame header off the network connection. Start time.Time // EndHeader is the time we finished reading the frame header off the network connection. End time.Time // Host is Host of the connection the frame header was read from. Host *HostInfo }
func (ObservedFrameHeader) String ¶
func (f ObservedFrameHeader) String() string
type ObservedQuery ¶
type ObservedQuery struct { Keyspace string Statement string Start time.Time // time immediately before the query was called End time.Time // time immediately after the query returned // Rows is the number of rows in the current iter. // In paginated queries, rows from previous scans are not counted. // Rows is not used in batch queries and remains at the default value Rows int // Host is the informations about the host that performed the query Host *HostInfo // The metrics per this host Metrics *hostMetrics // Err is the error in the query. // It only tracks network errors or errors of bad cassandra syntax, in particular selects with no match return nil error Err error // Attempt is the index of attempt at executing this query. // The first attempt is number zero and any retries have non-zero attempt number. Attempt int }
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 PoolConfig ¶
type PoolConfig struct { // HostSelectionPolicy sets the policy for selecting which host to use for a // given query (default: RoundRobinHostPolicy()) HostSelectionPolicy HostSelectionPolicy }
PoolConfig configures the connection pool used by the driver, it defaults to using a round-robin host selection policy and a round-robin connection selection policy for each host.
type Query ¶
type Query struct {
// contains filtered or unexported fields
}
Query represents a CQL statement that can be executed.
func (*Query) AddAttempts ¶
func (*Query) AddLatency ¶
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) Cancel ¶
func (q *Query) Cancel()
Deprecate: does nothing, cancel the context passed to WithContext
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) CustomPayload ¶
CustomPayload sets the custom payload level for this query.
func (*Query) DefaultTimestamp ¶
DefaultTimestamp will enable the with default timestamp flag on the query. If enable, this will replace the server side assigned timestamp as default timestamp. Note that a timestamp in the query itself will still override this timestamp. This is entirely optional.
Only available on protocol >= 3
func (*Query) GetConsistency ¶
func (q *Query) GetConsistency() Consistency
GetConsistency returns the currently configured consistency level for the query.
func (*Query) GetRoutingKey ¶
GetRoutingKey gets the routing key to use for routing this query. If a routing key has not been explicitly set, then the routing key will be constructed if possible using the keyspace's schema and the query info for this query statement. If the routing key cannot be determined then nil will be returned with no error. On any error condition, an error description will be returned.
func (*Query) Idempotent ¶
Idempotent marks the query as being idempotent or not depending on the value. Non-idempotent query won't be retried. See "Retries and speculative execution" in package docs for more details.
func (*Query) IsIdempotent ¶
IsIdempotent returns whether the query is marked as idempotent. Non-idempotent query won't be retried. See "Retries and speculative execution" in package docs for more details.
func (*Query) Iter ¶
Iter executes the query and returns an iterator capable of iterating over all results.
func (*Query) MapScan ¶
MapScan executes the query, copies the columns of the first selected row into the map pointed at by m and discards the rest. If no rows were selected, ErrNotFound is returned.
func (*Query) MapScanCAS ¶
MapScanCAS 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 previous values will be stored in dest map.
As for INSERT .. IF NOT EXISTS, previous values will be returned as if SELECT * FROM. So using ScanCAS with INSERT is inherently prone to column mismatching. MapScanCAS is added to capture them safely.
Example ¶
ExampleQuery_MapScanCAS demonstrates how to execute a single-statement lightweight transaction.
Output:
func (*Query) NoSkipMetadata ¶
NoSkipMetadata will override the internal result metadata cache so that the driver does not send skip_metadata for queries, this means that the result will always contain the metadata to parse the rows and will not reuse the metadata from the prepared statement. This should only be used to work around cassandra bugs, such as when using CAS operations which do not end in Cas.
See https://issues.apache.org/jira/browse/CASSANDRA-11099 https://github.com/gocql/gocql/issues/612
func (*Query) Observer ¶
func (q *Query) Observer(observer QueryObserver) *Query
Observer enables query-level observer on this query. The provided observer will be called every time this query is executed.
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 too low might decrease the performance. This feature is only available in Cassandra 2 and onwards.
func (*Query) PageState ¶
PageState sets the paging state for the query to resume paging from a specific point in time. Setting this will disable to query paging for this query, and must be used for all subsequent pages.
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) Release ¶
func (q *Query) Release()
Release releases a query back into a pool of queries. Released Queries cannot be reused.
Example:
qry := session.Query("SELECT * FROM my_table") qry.Exec() qry.Release()
func (*Query) RetryPolicy ¶
func (q *Query) RetryPolicy(r RetryPolicy) *Query
RetryPolicy sets the policy to use when retrying the query.
func (*Query) RoutingKey ¶
RoutingKey sets the routing key to use when a token aware connection pool is used to optimize the routing of this 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.
func (*Query) ScanCAS ¶
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 previous values will be stored in dest.
As for INSERT .. IF NOT EXISTS, previous values will be returned as if SELECT * FROM. So using ScanCAS with INSERT is inherently prone to column mismatching. Use MapScanCAS to capture them safely.
func (*Query) SerialConsistency ¶
func (q *Query) SerialConsistency(cons SerialConsistency) *Query
SerialConsistency sets the consistency level for the serial phase of conditional updates. That consistency can only be either SERIAL or LOCAL_SERIAL and if not present, it defaults to SERIAL. This option will be ignored for anything else that a conditional update/insert.
func (*Query) SetConsistency ¶
func (q *Query) SetConsistency(c Consistency)
Same as Consistency but without a return value
func (*Query) SetSpeculativeExecutionPolicy ¶
func (q *Query) SetSpeculativeExecutionPolicy(sp SpeculativeExecutionPolicy) *Query
SetSpeculativeExecutionPolicy sets the execution policy
func (*Query) Trace ¶
Trace enables tracing of this query. Look at the documentation of the Tracer interface to learn more about tracing.
func (*Query) WithContext ¶
WithContext returns a shallow copy of q with its context set to ctx.
The provided context controls the entire lifetime of executing a query, queries will be canceled and return once the context is canceled.
func (*Query) WithTimestamp ¶
WithTimestamp will enable the with default timestamp flag on the query like DefaultTimestamp does. But also allows to define value for timestamp. It works the same way as USING TIMESTAMP in the query itself, but should not break prepared query optimization.
Only available on protocol >= 3
type QueryInfo ¶
type QueryInfo struct { Id []byte Args []ColumnInfo Rval []ColumnInfo PKeyColumns []int }
type QueryObserver ¶
type QueryObserver interface { // ObserveQuery gets called on every query to cassandra, including all queries in an iterator when paging is enabled. // It doesn't get called if there is no query because the session is closed or there are no connections available. // The error reported only shows query errors, i.e. if a SELECT is valid but finds no matches it will be nil. ObserveQuery(context.Context, ObservedQuery) }
QueryObserver is the interface implemented by query observers / stat collectors.
Experimental, this interface and use may change
type ReadyPolicy ¶
type ReadyPolicy interface {
Ready() bool
}
ReadyPolicy defines a policy for when a HostSelectionPolicy can be used. After each host connects during session initialization, the Ready method will be called. If you only need a single Host to be up you can wrap a HostSelectionPolicy policy with SingleHostReadyPolicy.
type ReconnectionPolicy ¶
type ReconnectionPolicy interface { GetInterval(currentRetry int) time.Duration GetMaxRetries() int }
ReconnectionPolicy interface is used by gocql to determine if reconnection can be attempted after connection error. The interface allows gocql users to implement their own logic to determine how to attempt reconnection.
type RequestErrAlreadyExists ¶
type RequestErrCDCWriteFailure ¶
type RequestErrCDCWriteFailure struct {
// contains filtered or unexported fields
}
type RequestErrFunctionFailure ¶
type RequestErrReadFailure ¶
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 }
func (*RequestErrUnavailable) String ¶
func (e *RequestErrUnavailable) String() string
type RequestErrUnprepared ¶
type RequestErrUnprepared struct { StatementId []byte // contains filtered or unexported fields }
type RequestErrWriteFailure ¶
type RequestErrWriteTimeout ¶
type RequestErrWriteTimeout struct { Consistency Consistency Received int BlockFor int WriteType string // contains filtered or unexported fields }
type RequestError ¶
type RetryPolicy ¶
type RetryPolicy interface { Attempt(RetryableQuery) bool GetRetryType(error) RetryType }
RetryPolicy interface is used by gocql to determine if a query can be attempted again after a retryable error has been received. The interface allows gocql users to implement their own logic to determine if a query can be attempted again.
See SimpleRetryPolicy as an example of implementing and using a RetryPolicy interface.
type RetryableQuery ¶
type RetryableQuery interface { Attempts() int SetConsistency(c Consistency) GetConsistency() Consistency Context() context.Context }
RetryableQuery is an interface that represents a query or batch statement that exposes the correct functions for the retry policy logic to evaluate correctly.
type Scanner ¶
type Scanner interface { // Next advances the row pointer to point at the next row, the row is valid until // the next call of Next. It returns true if there is a row which is available to be // scanned into with Scan. // Next must be called before every call to Scan. Next() bool // Scan copies the current row's columns into dest. If the length of dest does not equal // the number of columns returned in the row an error is returned. If an error is encountered // when unmarshalling a column into the value in dest an error is returned and the row is invalidated // until the next call to Next. // Next must be called before calling Scan, if it is not an error is returned. Scan(...interface{}) error // Err returns the if there was one during iteration that resulted in iteration being unable to complete. // Err will also release resources held by the iterator, the Scanner should not used after being called. Err() error }
type SelectedHost ¶
SelectedHost is an interface returned when picking a host from a host selection policy.
type SerialConsistency ¶
type SerialConsistency uint16
const ( Serial SerialConsistency = 0x08 LocalSerial SerialConsistency = 0x09 )
func (SerialConsistency) MarshalText ¶
func (s SerialConsistency) MarshalText() (text []byte, err error)
func (SerialConsistency) String ¶
func (s SerialConsistency) String() string
func (*SerialConsistency) UnmarshalText ¶
func (s *SerialConsistency) UnmarshalText(text []byte) error
type Session ¶
type Session struct {
// 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 convenient query builder and automatically sets a default consistency level on all operations that do not have a consistency level set.
func NewSession ¶
func NewSession(cfg ClusterConfig) (*Session, error)
NewSession wraps an existing Node.
func (*Session) AwaitSchemaAgreement ¶
AwaitSchemaAgreement will wait until schema versions across all nodes in the cluster are the same (as seen from the point of view of the control connection). The maximum amount of time this takes is governed by the MaxWaitSchemaAgreement setting in the configuration (default: 60s). AwaitSchemaAgreement returns an error in case schema versions are not the same after the timeout specified in MaxWaitSchemaAgreement elapses.
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) ExecuteBatchCAS ¶
func (s *Session) ExecuteBatchCAS(batch *Batch, dest ...interface{}) (applied bool, iter *Iter, err error)
ExecuteBatchCAS executes a batch operation and returns true if successful and an iterator (to scan additional rows if more than one conditional statement) was sent. Further scans on the interator must also remember to include the applied boolean as the first argument to *Iter.Scan
func (*Session) KeyspaceMetadata ¶
func (s *Session) KeyspaceMetadata(keyspace string) (*KeyspaceMetadata, error)
KeyspaceMetadata returns the schema metadata for the keyspace specified. Returns an error if the keyspace does not exist.
func (*Session) MapExecuteBatchCAS ¶
func (s *Session) MapExecuteBatchCAS(batch *Batch, dest map[string]interface{}) (applied bool, iter *Iter, err error)
MapExecuteBatchCAS executes a batch operation much like ExecuteBatchCAS, however it accepts a map rather than a list of arguments for the initial scan.
Example ¶
ExampleSession_MapExecuteBatchCAS demonstrates how to execute a batch lightweight transaction.
Output:
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 SetHosts ¶
type SetHosts interface {
SetHosts(hosts []*HostInfo)
}
interface to implement to receive the host information
type SetPartitioner ¶
type SetPartitioner interface {
SetPartitioner(partitioner string)
}
interface to implement to receive the partitioner value
type SimpleConvictionPolicy ¶
type SimpleConvictionPolicy struct { }
SimpleConvictionPolicy implements a ConvictionPolicy which convicts all hosts regardless of error
func (*SimpleConvictionPolicy) AddFailure ¶
func (e *SimpleConvictionPolicy) AddFailure(error error, host *HostInfo) bool
func (*SimpleConvictionPolicy) Reset ¶
func (e *SimpleConvictionPolicy) Reset(host *HostInfo)
type SimpleRetryPolicy ¶
type SimpleRetryPolicy struct {
NumRetries int //Number of times to retry a query
}
SimpleRetryPolicy has simple logic for attempting a query a fixed number of times.
See below for examples of usage:
//Assign to the cluster cluster.RetryPolicy = &gocql.SimpleRetryPolicy{NumRetries: 3} //Assign to a query query.RetryPolicy(&gocql.SimpleRetryPolicy{NumRetries: 1})
func (*SimpleRetryPolicy) Attempt ¶
func (s *SimpleRetryPolicy) Attempt(q RetryableQuery) bool
Attempt tells gocql to attempt the query again based on query.Attempts being less than the NumRetries defined in the policy.
func (*SimpleRetryPolicy) GetRetryType ¶
func (s *SimpleRetryPolicy) GetRetryType(err error) RetryType
type SimpleSpeculativeExecution ¶
func (*SimpleSpeculativeExecution) Attempts ¶
func (sp *SimpleSpeculativeExecution) Attempts() int
func (*SimpleSpeculativeExecution) Delay ¶
func (sp *SimpleSpeculativeExecution) Delay() time.Duration
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 SslOptions ¶
type SslOptions struct { *tls.Config // CertPath and KeyPath are optional depending on server // config, but both fields must be omitted to avoid using a // client certificate CertPath string KeyPath string CaPath string //optional depending on server config // If you want to verify the hostname and server cert (like a wildcard for cass cluster) then you should turn this // on. // This option is basically the inverse of tls.Config.InsecureSkipVerify. // See InsecureSkipVerify in http://golang.org/pkg/crypto/tls/ for more info. // // See SslOptions documentation to see how EnableHostVerification interacts with the provided tls.Config. EnableHostVerification bool }
SslOptions configures TLS use.
Warning: Due to historical reasons, the SslOptions is insecure by default, so you need to set EnableHostVerification to true if no Config is set. Most users should set SslOptions.Config to a *tls.Config. SslOptions and Config.InsecureSkipVerify interact as follows:
Config.InsecureSkipVerify | EnableHostVerification | Result Config is nil | false | do not verify host Config is nil | true | verify host false | false | verify host true | false | do not verify host false | true | verify host true | true | verify host
type StdLogger ¶
type StdLogger interface { Print(v ...interface{}) Printf(format string, v ...interface{}) Println(v ...interface{}) }
var Logger StdLogger = &defaultLogger{}
type TableMetadata ¶
type TableMetadata struct { Keyspace string Name string KeyValidator string Comparator string DefaultValidator string KeyAliases []string ColumnAliases []string ValueAlias string PartitionKey []*ColumnMetadata ClusteringColumns []*ColumnMetadata Columns map[string]*ColumnMetadata OrderedColumns []string }
schema metadata for a table (a.k.a. column family)
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 TupleTypeInfo ¶
type TupleTypeInfo struct { NativeType Elems []TypeInfo }
func (TupleTypeInfo) New ¶
func (t TupleTypeInfo) New() interface{}
func (TupleTypeInfo) String ¶
func (t TupleTypeInfo) String() string
type Type ¶
type Type int
String returns a human readable name for the Cassandra datatype described by t. 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 TypeText Type = 0x000A TypeTimestamp Type = 0x000B TypeUUID Type = 0x000C TypeVarchar Type = 0x000D TypeVarint Type = 0x000E TypeTimeUUID Type = 0x000F TypeInet Type = 0x0010 TypeDate Type = 0x0011 TypeTime Type = 0x0012 TypeSmallInt Type = 0x0013 TypeTinyInt Type = 0x0014 TypeDuration Type = 0x0015 TypeList Type = 0x0020 TypeMap Type = 0x0021 TypeSet Type = 0x0022 TypeUDT Type = 0x0030 TypeTuple Type = 0x0031 )
type TypeInfo ¶
type TypeInfo interface { Type() Type Version() byte Custom() string // New creates a pointer to an empty version of whatever type // is referenced by the TypeInfo receiver New() interface{} }
TypeInfo describes a Cassandra specific data type.
type UDTMarshaler ¶
type UDTMarshaler interface { // MarshalUDT will be called for each field in the the UDT returned by Cassandra, // the implementor should marshal the type to return by for example calling // Marshal. MarshalUDT(name string, info TypeInfo) ([]byte, error) }
UDTMarshaler is an interface which should be implemented by users wishing to handle encoding UDT types to sent to Cassandra. Note: due to current implentations methods defined for this interface must be value receivers not pointer receivers.
type UDTTypeInfo ¶
type UDTTypeInfo struct { NativeType KeySpace string Name string Elements []UDTField }
func (UDTTypeInfo) New ¶
func (u UDTTypeInfo) New() interface{}
func (UDTTypeInfo) String ¶
func (u UDTTypeInfo) String() string
type UDTUnmarshaler ¶
type UDTUnmarshaler interface { // UnmarshalUDT will be called for each field in the UDT return by Cassandra, // the implementor should unmarshal the data into the value of their chosing, // for example by calling Unmarshal. UnmarshalUDT(name string, info TypeInfo, data []byte) error }
UDTUnmarshaler should be implemented by users wanting to implement custom UDT unmarshaling.
type UUID ¶
type UUID [16]byte
func MaxTimeUUID ¶
MaxTimeUUID generates a "fake" time based UUID (version 1) which will be the biggest possible UUID generated for the provided timestamp.
UUIDs generated by this function are not unique and are mostly suitable only in queries to select a time range of a Cassandra's TimeUUID column.
func MinTimeUUID ¶
MinTimeUUID generates a "fake" time based UUID (version 1) which will be the smallest possible UUID generated for the provided timestamp.
UUIDs generated by this function are not unique and are mostly suitable only in queries to select a time range of a Cassandra's TimeUUID column.
func ParseUUID ¶
ParseUUID parses a 32 digit hexadecimal number (that might contain hypens) representing 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 TimeUUIDWith ¶
TimeUUIDWith generates a new time based UUID (version 1) as described in RFC4122 with given parameters. t is the number of 100's of nanoseconds since 15 Oct 1582 (60bits). clock is the number of clock sequence (14bits). node is a slice to gurarantee the uniqueness of the UUID (up to 6bytes). Note: calling this function does not increment the static clock sequence.
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) Clock ¶
Clock extracts the clock sequence of this UUID. It will return zero if the UUID is not a time based UUID (version 1).
func (UUID) MarshalText ¶
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).
func (*UUID) UnmarshalText ¶
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.
type UserTypeMetadata ¶
Source Files
¶
- address_translators.go
- cluster.go
- compressor.go
- conn.go
- connectionpool.go
- control.go
- cqltypes.go
- debug_off.go
- doc.go
- errors.go
- events.go
- filters.go
- frame.go
- helpers.go
- host_source.go
- logger.go
- marshal.go
- metadata.go
- policies.go
- prepared_cache.go
- query_executor.go
- ring.go
- session.go
- token.go
- topology.go
- uuid.go