Package gocql implements a fast and robust Cassandra client for the Go programming language.
Go Shell
Latest commit 1f87449 Feb 14, 2017 @Zariel Zariel committed on GitHub Merge pull request #859 from thrawn01/improve-mapscan-docs
Improved MapScan() documentation and added new MapScan test
Permalink
Failed to load latest commit information.
internal Fix two bugs in stream id allocation. (#707) Apr 15, 2016
testdata add benchmark for result parsing Oct 18, 2015
.gitignore add .idea to .gitignore Mar 21, 2016
.travis.yml travis: update to 3.0 Sep 27, 2016
AUTHORS Added ConnectTimeout for initial connections to nodes Feb 9, 2017
CONTRIBUTING.md update README to match Travis CI Sep 15, 2016
LICENSE Remove references to google in LICENSE Sep 26, 2016
README.md suggest journey, Gemnasium’s fork of migrate library Feb 7, 2017
address_translators.go adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
address_translators_test.go adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
batch_test.go fix batch error propogation Feb 25, 2016
cass1batch_test.go should close the session regardless of failure Feb 4, 2016
cassandra_test.go Improved MapScan() documentation and added new MapScan test Feb 14, 2017
cluster.go Added ConnectTimeout for initial connections to nodes Feb 9, 2017
cluster_test.go adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
common_test.go adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
compressor.go Update snappy import in SnappyCompressor. Jul 17, 2015
compressor_test.go Update snappy import in SnappyCompressor. Jul 17, 2015
conn.go Added ConnectTimeout for initial connections to nodes Feb 9, 2017
conn_test.go Added ConnectTimeout for initial connections to nodes Feb 9, 2017
connectionpool.go Added ConnectTimeout for initial connections to nodes Feb 9, 2017
control.go control.go: fix race condition on randr Jan 13, 2017
control_test.go Add support to discovery protocol version Oct 30, 2016
debug_off.go rename debug -> gocqlDebug Feb 2, 2016
debug_on.go rename debug -> gocqlDebug Feb 2, 2016
doc.go Update the copyright date Apr 9, 2015
errors.go frame: add writeFailure error Apr 30, 2016
errors_test.go use control connection to create tables in tests Oct 18, 2015
events.go replace standard logger with the global Logger Nov 22, 2016
events_ccm_test.go dont build ccm tests as they will be rewritten Oct 24, 2016
events_test.go typo fix: Debouncer Oct 19, 2016
filters.go change HostInfo.Peer to be an IP Oct 24, 2016
filters_test.go change HostInfo.Peer to be an IP Oct 24, 2016
frame.go add the Warnings function on Iter Nov 22, 2016
frame_test.go Non-panic ParseConsistency added Aug 16, 2016
framer_bench_test.go add benchmark for result parsing Oct 18, 2015
fuzz.go use the version from the read header version when parsing the frames … Jun 12, 2015
helpers.go Improved MapScan() documentation and added new MapScan test Feb 14, 2017
host_source.go replace standard logger with the global Logger Nov 22, 2016
host_source_test.go skip TestSchemaReset on cassandra < 2.1.3 Feb 6, 2016
integration.sh adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
logger.go Added ConnectTimeout for initial connections to nodes Feb 9, 2017
marshal.go marshalUDT: allow not using all the UDT fields Nov 29, 2016
marshal_test.go marshall: support small and tiny ints, fix uint May 14, 2016
metadata.go When attempting to fetch a keyspace's metadata, if the keyspace doesn't Jan 19, 2017
metadata_test.go metadata: dont use strings for column kinds Oct 22, 2016
policies.go replace standard logger with the global Logger Nov 22, 2016
policies_test.go Merge pull request #811 from Dieterbe/test-simpleretrypolicy-more-tho… Oct 26, 2016
prepared_cache.go Revert "Use RWMutex in prepared statement cache" Oct 28, 2016
query_executor.go change HostInfo.Peer to be an IP Oct 24, 2016
ring.go Add support to discovery protocol version Oct 30, 2016
ring_test.go change HostInfo.Peer to be an IP Oct 24, 2016
session.go Update godoc for KeyspaceMetadata() indicating what the function retu… Jan 19, 2017
session_connect_test.go adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
session_test.go adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
stress_test.go cluster: remove NumStreams config Nov 21, 2015
token.go gofmt + authors Nov 7, 2016
token_test.go change HostInfo.Peer to be an IP Oct 24, 2016
topology.go check for nil pointers before dereferencing Aug 21, 2013
topology_test.go Try to delineate between unit and integration tests Oct 30, 2014
tuple_test.go correctly handle tuples in MapScan Jan 10, 2016
udt_test.go adding AddressTranslator interface and impl for use in ec2 Nov 3, 2016
uuid.go uuid: implement text marshalling functions Jan 10, 2016
uuid_test.go uuid: implement text marshalling functions Jan 10, 2016
wiki_test.go gofmt -s Feb 4, 2016

README.md

gocql

Join the chat at https://gitter.im/gocql/gocql Build Status GoDoc

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.0.x
1.6 yes yes yes
1.7 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 and Unmarshaler 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

/* Before you execute the program, Launch `cqlsh` and execute:
create keyspace example with replication = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
create table example.tweet(timeline text, id UUID, text text, PRIMARY KEY(id));
create index on example.tweet(timeline);
*/
package main

import (
    "fmt"
    "log"

    "github.com/gocql/gocql"
)

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

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

    var id gocql.UUID
    var text string

    /* Search for a specific set of records whose 'timeline' column matches
     * the value 'me'. The secondary index that we created earlier will be
     * used for optimizing the search */
    if err := session.Query(`SELECT id, text FROM tweet WHERE timeline = ? LIMIT 1`,
        "me").Consistency(gocql.One).Scan(&id, &text); err != nil {
        log.Fatal(err)
    }
    fmt.Println("Tweet:", id, text)

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

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 the SliceMap() API. This returns a slice of row maps keyed by CQL column mames. 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 call MapScan() which returns map[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.
  • 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:

  • 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

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 traditional database/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.