Installation

Installation

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.

Compatibility

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_NONBLOCK flag 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.

Dependencies

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 Excon for better performance.
• yajl-ruby, json, json-pure, 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

RubyGems

The Riak Ruby client is distributed as a gem package called riak-client. You can simply install it using the gem command:

$ 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

Bundler

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 project:

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 Gemfile like so:

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 to the 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'

Additional documentation

Most of the code in the Ruby client API is documented using YARD, and is available online at RDoc.info.

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?