If you're reading this on GitHub, please note that this is the readme for the development version and that some features described here might not yet have been released. You can find the documentation for latest version through ruby driver docs or via the release tags, e.g. v1.0.0-beta.3.
A Ruby client driver for Apache Cassandra. This driver works exclusively with the Cassandra Query Language version 3 (CQL3) and Cassandra's native protocol.
- Code: https://github.com/datastax/ruby-driver
- Docs: http://datastax.github.io/ruby-driver/
- Jira: https://datastax-oss.atlassian.net/browse/RUBY
- Mailing List: https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user
- IRC: #datastax-drivers on irc.freenode.net
- Twitter: Follow the latest news about DataStax Drivers - @avalanche123, @mfiguiere, @al3xandru
This driver is based on the cql-rb gem by Theo Hultberg and we added support for:
- Asynchronous execution
- One-off, prepared and batch statements
- Automatic peer discovery and cluster metadata with support for change notifications
- Various load-balancing, retry and reconnection policies with ability to write your own
- SSL encryption
- Flexible and robust error handling
- Per-request execution information and tracing
- Configurable address resolution
Check out the slides from Ruby Driver Explained for a detailed overview of the Ruby Driver architecture.
This driver works exclusively with the Cassandra Query Language v3 (CQL3) and Cassandra's native protocol. The current version works with:
- Apache Cassandra versions 1.2, 2.0 and partially 2.1
- DataStax Enterprise 3.1, 3.2, 4.0 and 4.5
- Ruby (MRI) 1.9.3, 2.0 and 2.1
- JRuby 1.7
- Rubinius 2.2
Note: Apache Cassandra 2.1 support is limited to the Cassandra 2.0 API, e.g. no user-defined types.
Note: JRuby 1.6 is not officially supported, although 1.6.8 should work.
require 'cassandra'
cluster = Cassandra.cluster # connects to localhost by default
cluster.each_host do |host| # automatically discovers all peers
puts "Host #{host.ip}: id=#{host.id} datacenter=#{host.datacenter} rack=#{host.rack}"
end
keyspace = 'system'
session = cluster.connect(keyspace) # create session, optionally scoped to a keyspace, to execute queries
future = session.execute_async('SELECT keyspace_name, columnfamily_name FROM schema_columnfamilies') # fully asynchronous api
future.on_success do |rows|
rows.each do |row|
puts "The keyspace #{row['keyspace_name']} has a table called #{row['columnfamily_name']}"
end
end
future.joinNote: The host you specify is just a seed node, the driver will automatically discover all peers in the cluster.
Read more:
Install via rubygems
gem install cassandra-driverInstall via Gemfile
gem 'cassandra-driver'Note: if you want to use compression you should also install snappy or lz4-ruby. Read more about compression.
Some of the new features added to the driver have unfortunately led to changes in the original cql-rb API. In the examples directory, you can find an example of how to wrap the ruby driver to achieve almost complete interface parity with cql-rb to assist you with gradual upgrade.
Current release introduces the following new features:
- Ability to disable automatic schema synchronization
- Schema change event storm protection using a sliding delay
Cassandra::LoadBalancing::Policy#teardownfor cleaning up resourcesCassandra::Cluster#refresh_schemafor manually refreshing schema metadata- Host list randomization to prevent hotspots between multiple clients
- Future listeners run in a dedicated threadpool to not block the reactor
The DataStax Ruby Driver uses the awesome Cucumber Framework for both end-to-end, or acceptance, testing and constructing documentation. All of the features supported by the driver have appropriate acceptance tests with easy-to-copy code examples in the features/ directory.
If you don't feel like reading through the following instructions on how to run ruby-driver tests, feel free to check out .travis.yml for the entire build code.
- Check out the driver codebase and install test dependencies:
git clone https://github.com/datastax/ruby-driver.git
cd ruby-driver
bundle install --without docs-
Run tests:
bundle exec cucumber # runs end-to-end tests (or bundle exec rake cucumber)
bundle exec rspec # runs unit tests (or bundle exec rake rspec)
bundle exec rake integration # run integration tests
bundle exec rake test # run both as well as integration testsCheck out the releases on GitHub and changelog. Version numbering follows the semantic versioning scheme.
Private and experimental APIs, defined as whatever is not in the public API documentation, i.e. classes and methods marked as @private, will change without warning. If you've been recommended to try an experimental API by the maintainers, please let them know if you depend on that API. Experimental APIs will eventually become public, and knowing how they are used helps in determining their maturity.
Prereleases will be stable, in the sense that they will have finished and properly tested features only, but may introduce APIs that will change before the final release. Please use the prereleases and report bugs, but don't deploy them to production without consulting the maintainers, or doing extensive testing yourself. If you do deploy to production please let the maintainers know as this helps determining the maturity of the release.
- JRuby 1.6 is not officially supported, although 1.6.8 should work, if you're stuck in JRuby 1.6.8 try and see if it works for you.
- Because the driver reactor is using
IO.select, the maximum number of tcp connections allowed is 1024. - Because the driver uses
IO#write_nonblock, Windows is not supported.
Please refer to the usage documentation for more information on common pitfalls
This driver is based on the original work of Theo Hultberg on cql-rb and adds a series of advanced features that are common across all other DataStax drivers for Apache Cassandra.
The development effort to provide an up to date, high performance, fully featured Ruby Driver for Apache Cassandra will continue on this project, while cql-rb will be discontinued.
Copyright 2013-2014 DataStax, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.