Clone this wiki locally
Welcome to the Installation guide for the Riak Ruby Client! At the end of this guide, you should be familiar with:
- Installing the client package
- Importing the client into your application
- Where to find additional documentation
This and the other guides in this wiki assume you have Riak installed locally. If you don't have Riak already, please read and follow how to install Riak and then come back to this guide.
The Ruby client officially supports MRI (Matz's Ruby Implementation, also known as "C Ruby") versions 1.8.7 and later, and JRuby 1.6 or later, and Rubinius 1.2 or later. To find out what version of Ruby you have installed, run this at a terminal prompt:
$ ruby -v ruby 1.9.3p125 (2012-02-16 revision 34643) [x86_64-darwin10.8.0]
You also need a recent version of RubyGems installed for the client's dependencies. You can find out what version of RubyGems is installed via the terminal:
$ gem -v 1.8.21
Known Compatibility Issues
We recommend using MRI Ruby 1.9.3 with the client. While almost all client functionality works correctly on other versions, there are a few gotchas:
- JRuby will occasionally, unpredictably fail to open the Riak
console. (See Node and Cluster Generation) This is related to
lacking support for the
O_NONBLOCKflag on the JVM when opening the console pipes. The existing workaround is not 100% reliable.
- Rubinius does not pass the entire test suite.
As with all compatibility issues, your experience may vary. We encourage you to report new compatibility issues you discover on the issue tracker. We also encourage you to submit pull-requests fixing these issues.
The Ruby client depends on some other libraries to do its work:
beefcake- for working with Riak's Protocol Buffers-based protocol.
builder- for constructing XML when updating Riak Search indexes.
multi_json- many responses from Riak are in JSON format.
i18n- supporting localization of error messages.
Additionally, you may want to install these libraries for use with the client:
excon- a high-performance, pure-Ruby HTTP client. By default, we use
Net::HTTP(part of the Ruby standard library) with Riak's HTTP interface, but heavy users of the HTTP protocol might want
Exconfor better performance.
oj- These JSON libraries improve over the default engine packaged with
multi_json. If you are storing lots of JSON in Riak, or frequently working with MapReduce or bucket properties, you might want one of these more robust libraries for JSON serialization.
Downloading and Installing
The Riak Ruby client is distributed as a gem package called
riak-client. You can simply
install it using the
$ gem install riak-client Fetching: i18n-0.6.0.gem (100%) Fetching: builder-3.0.0.gem (100%) Fetching: beefcake-0.3.7.gem (100%) Fetching: multi_json-1.3.2.gem (100%) Fetching: riak-client-1.0.3.gem (100%) Successfully installed i18n-0.6.0 Successfully installed builder-3.0.0 Successfully installed beefcake-0.3.7 Successfully installed multi_json-1.3.2 Successfully installed riak-client-1.0.3 5 gems installed
However, nowadays most Ruby projects use
Bundler to manage external libraries. If you
have Bundler installed, modify the
Gemfile to add the client to your
gem 'riak-client', '~> 1.0.3'
Now you can use the
bundle install command to install the client:
$ bundle install Fetching source index for http://rubygems.org/ Installing beefcake (0.3.7) Installing builder (3.0.0) Installing i18n (0.6.0) Installing multi_json (1.3.2) Installing riak-client (1.0.3) Using bundler (1.0.21) Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
Living on the Edge
If you want to receive the most bleeding-edge features of the client
in your project, you can use the
:git option in your
gem 'riak-client', :git => "git://github.com/basho/riak-ruby-client.git"
By default, that will give you the latest version that has been pushed
master branch. If instead you want the latest stable version,
specify the branch as well:
gem 'riak-client', :git => 'git://github.com/basho/riak-ruby-client.git', :branch => '1.0-stable'
Import the code
Once the client is in your local RubyGems repository or bundle, your application can make use of it with a single require, assuming it already has required RubyGems or setup Bundler:
require 'rubygems' require 'bundler/setup' require 'riak'
General documentation about Riak can be found on the Riak Wiki.
What to do next
Congratulations, you finished the "Installation" guide! Now that you've got the client installed, why not connect to Riak?