README.md

gocql

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

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

Production Stability

The underlying framing code was rewritten as part of #339 and as such may have unforseen bugs. If you run into a bug related to wire framing, please raise a ticket and we will try to resolve this as soon as we can. If you require a stable version to pin your production app against, we have tagged the previous stable version in source code, so you can build against this. The tag is called 1st_gen_framing (180456fef0a3c6d02c51dc7211f49b55e9315867). This note will be removed as the new generation framing code base matures.

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	1.2.19	2.0.14	2.1.5
1.3	yes	yes	yes
1.4	yes	yes	yes

Sunsetting Model

In general, the gocql team will focus on supporting the current and previous versions of Golang. gocql may still work with older versions of Golang, but offical 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 conversations between Cassandra and Go
  • Support for all common types including sets, lists and maps
  • Custom types can implement a Marshaler and Unmarshaler interface
  • Strict type conversations without any loss of precision
  • Built-In support for UUIDs (version 1 and 4)
• Support for logged, unlogged and counter batches
• Cluster management
  • Automatic reconnect on connection failures with exponential falloff
  • Round robin distribution of queries to different hosts
  • Round robin distribution of queries to different connections on a host
  • Each connection can execute up to n concurrent queries (whereby n is the limit set by the protocol version the client chooses to use)
  • Optional automatic discovery of nodes
  • Optional support for periodic node discovery via system.peers
  • 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
• Experimental support for 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
• An API to access the schema metadata of a given keyspace

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

Important Default Keyspace Changes

gocql no longer supports executing "use " statements to simplfy 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.

Ecosphere

The following community maintained tools are known to integrate with gocql:

• migrate is a migration handling tool written in Go 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 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 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 whilst working the library.

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-2015 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.