Ruby Client Library

Communicate with Couchbase Server using Ruby

Note: Version 1.2 is the most recent release of this SDK.  It is recommended for all deployments.

Getting Started

Here is a video that demonstrates the use of the Couchbase client library with Ruby:

Up and Running with Couchbase Ruby Client from Couchbase on Vimeo.

Download, Installation and Use

Here's a quick outline of what you'll learn.

  1. Installing the Ruby Couchbase Client (Gem) Couchbase.

  2. Writing a simple program to demonstrate connecting to Couchbase and saving some data.

  3. Exploring some of the API methods that will take you further than the simple program.

Now that you've installed Couchbase and have probably created a cluster of Couchbase servers.  Before we begin, you should ensure that you have Couchbase up and running on your development machine

It is time to install the client library for Ruby, and start manipulating data.

Installing the Couchbase Client Library

There are a few prerequisites to have the Ruby environment up and running for accessing Couchbase. We recommend the following:

Support for this gem with JRuby is under development and will be available soon.

You can verify that Ruby and RubyGems are installed by typing the following commands:

shell> ruby -v


shell> gem --version

The Ruby version should be 1.8.7 or higher and the gem version should be 1.3.6. or higher.

  1. Install the package libevent.
  2. Then install the Couchbase C client library, also known as libcouchbase.  
  3. You will also need to install libvbucket which is also part of the Couchbase C client library.
  4. You may also need to install rubygems if you have not installed it already.
  5. Once you have rubygems installed you can simply use rubygems to install Couchbase:
shell> gem install couchbase

Hello Couchbase

Let's look at a very simple Ruby program to interact with Couchbase. We want to set a key and on subsequent runs of the application we will output the key if it exists and create it if it does not. We'll also set a Time to Live (TTL) property so that the key we set will expire after 10 seconds.

If you want to follow along with this example, to make things easier we've provided a repository of the code used in this tutorial. To that we've added a Gemfile for use with Bundler.

Open up a new Terminal window and type the following:

​​$ git clone
$ cd couchbase-examples-ruby

Now that you have a copy of the code, let's look at what's happening.

Listing 1: Gemfile

source ""

gem "active_support"
gem "couchbase"

In the above we simply require all Gem dependencies for the hello-world.rb example. If you didn't have them already they will be installed when you run bundle install as below.

$ sudo bundle install

or, if you have already installed the dependencies, you can run the sample program by simply running the command

$ ruby hello-world.rb

Listing 2: hello-world.rb

require 'rubygems'
require 'couchbase'

client = ""
client.quiet = false
  spoon = client.get "spoon"
  puts spoon
rescue Couchbase::Error::NotFound => e
  puts "There is no spoon."
  client.set "spoon", "Hello World!", :ttl => 10

The first 2 lines are to load the required gems.

We then create a new connection to our Couchbase Server. Remember to change the connection details if you are working with couchbase remotely or on another port.

The last few lines are the meat of what's happening, let's go through them in more detail:

rescue Couchbase::Error::NotFound => e

If we try to retrieve a key from Couchbase that does not exist it will raise a Couchbase::Error::NotFound error. So to be able to handle this we start a begin/rescue block and specify we want to only rescue from that error.

spoon = client.get "spoon"
puts spoon

Now we attempt to get the contents of the key "spoon". If it exists, we continue and output the value of that key.

puts "There is no spoon."
client.set "spoon", "Hello World!", 10

Lastly if the key doesn't exist based on our attempt to get it raises raises a Couchbase::Error::NotFound error then the rescue block will be triggered. In the rescue block, we're just outputting to the terminal and then setting a value for our key "spoon". For the purposes of the example we're passing a 3rd (optional) paramter to the set method specifying a TTL Time to Live (expiry time in seconds).

That's it. We're ready to run our first Couchbase program.

ruby hello-world.rb

The first time you run the program it should produce the following output

shell> couchbase-examples-ruby  ruby hello-world.rb
There is no spoon.

If you are to run it again within 10 seconds it should produce this output

shell> couchbase-examples-ruby  ruby hello-world.rb
Hello World!

If you are to run it after 10 seconds it should produce the following output based on the Time To Live (TTL) specified.

shell> couchbase-examples-ruby  ruby hello-world.rb
There is no spoon.

Way to go! You've just interacted with Couchbase for the first time. We've looked at getting and setting the value of a key and expiring the cache.