= cassandra

A Ruby client for the Cassandra distributed database. 

== License

Copyright 2009, 2010 Twitter, Inc. See included LICENSE file. Portions copyright 2004-2009 David Heinemeier Hansson, and used with permission.

== Features

* clean encapsulation of the Thrift API
* compatible UUID and Long classes, for GUID generation
* Ruby 1.9 compatibility

The Github source repository is {here}[http://github.com/fauna/cassandra/]. Patches and contributions are very welcome.

== Installation

You need Ruby 1.8 or 1.9. If you have those, just run:

  sudo gem install cassandra

Cassandra itself is a rapidly moving target. In order to get a working server, use the `bin/cassandra_helper` script:

  cassandra_helper cassandra

A server will be installed in `$HOME/cassandra/server`, and started in debug mode.

WARNING: Don't use the test folder for your data, as it will get overwritten when you update the gem.

== Usage

Now, start IRb and require the library, which defaults to version 0.6 of the Cassandra API:

  require 'cassandra'

Alternatively, you can specify a version of the Cassandra API to use:

  require 'cassandra/0.6'

or

  require 'cassandra/0.7'

Connect to a server and keyspace:

  client = Cassandra.new('Twitter', '127.0.0.1:9160')

Login on server if the keyspace require authentication:

  client.login!('username','password')

Insert into a column family. You can insert a `Cassandra::OrderedHash`, or a regular Hash, if order doesn't matter:

  client.insert(:Users, "5", {'screen_name' => "buttonscat"})

Insert into a super column family:

  client.insert(:UserRelationships, "5", {"user_timeline" => {UUID.new => "1"}})

Query a super column:

  timeline = client.get(:UserRelationships, "5", "user_timeline")

The returned result will always be a Cassandra::OrderedHash.

See Cassandra for more methods.

== Configuration

By default, cassandra is setup to listen on localhost. If you want to move your clients to another host, you're going to need to change which interface it binds to in the storage-conf.xml. You should also change the seed address.

== Node Auto-Discovery

The list of hosts you pass to the client is only used to auto-discover all the nodes in your cluster. You don't need to give the client a list of all of your nodes.

== Further reading

* {Up and Running With Cassandra}[http://blog.evanweaver.com/articles/2009/07/06/up-and-running-with-cassandra]

== Reporting problems

The Github issue tracker is {here}[http://github.com/fauna/cassandra/issues]. If you have problems with this library or Cassandra itself, please use the {cassandra-user mailing list}[http://mail-archives.apache.org/mod_mbox/incubator-cassandra-user/].