Skip to content
A tiny shim between you and riak-client. Reads config/database.yml and generates sensible bucket names.
Find file
Pull request Compare This branch is 67 commits behind mkb:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Riak Shim

A teeny shim between your code and the riak-client gem. Reads database configuration out of config/database.yml and derives bucket names from your class names and an appropriate prefix.

Riak is a database from the good people at Basho. Check it out:

Build Status Dependency Status Code Climate


Add this line to your application's Gemfile:

gem 'riak-shim'

And then execute:

$ bundle

Or install it yourself as:

$ gem install riak-shim


Create a config/database.yml containing the details of your Riak setup like so:

development: &default
  bucket_prefix: myapp_dev_
  host: localhost
  http_port: 8098

  <<: *default
  bucket_prefix: myapp_test_

bucket_prefix will be prefixed to each bucket name, allowing you to point multiple applications (or multiple copies of the same application) at a single Riak install. During development, this prevents you from stepping on your own toes.

Converting a model to use Riak

In any class you wish to persist, you must include the module:

require 'riak-shim'
include Riak::Shim::Persistable

Then, write a #to_hash method which returns a hash representing your object (and consequently, what you are going to store):

def to_hash
  # Return hashified version of your class

You'll use Class#from_hash to create an instance from the hash which was pulled from Riak:

def self.from_hash(data)
  your_obj = new = data['foo']
  # Return a fresh instance of your class populated by the hash provided
  return your_obj

You can now save instances of your class by calling #save and later retrieve them from Riak by calling...


Secondary indexes

Secondary indexes in Riak allow you to query based on the contents of a particular field. If you'd like to look up your data by the contents of fields, define #fields_to_index and return the names of any fields you wish to query on. When you #save an instance of YourClass, riak-shim will populate a secondary index for that field.

def fields_to_index
  # Return an Array of hash keys you would like placed into a secondary index.

The for_index method retrieves all records whose value for the given index matches:

YourClass.for_index(index_name, value)

...where index_name is what you defined in fields_to_index plus the suffix "_bin" .

The value is what you want to look up.

Return value is an Array of instances of your class matching the query.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


  • Examples directory
  • Revisit tests
  • find less horrible way to deal with index names
Something went wrong with that request. Please try again.