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 or create it if it does not. We'll also set a Time to Live (TTL) 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.

If you want a head start you can grab the example code and get going straight away. Open up a new Terminal window and type the following:

shell> git clone git@github.com:avsej/couchbase-examples-ruby.git
shell> cd couchbase-examples-ruby
shell> sudo bundle install

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

Listing 1: Gemfile

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.

shell> sudo bundle install

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

shell> ruby hello-world.rb

Listing 2: hello-world.rb

require 'rubygems'
require 'couchbase'

client = Couchbase.connect("http://127.0.0.1:8091/pools/default")
client.quiet = false
begin
  spoon = client.get "spoon"
  puts spoon
rescue Couchbase::Error::NotFound => e
  puts "There is no spoon."
  client.set "spoon", "Hello World!", :ttl => 10
end

The first 3 lines are some bootstrap code for Bundler, to load it and then have it load all the Gems specified in our Gemfile.

We then create a new connection to our Couchbase Server. Remember to change the connection details 127.0.0.1:8091 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:

begin
  ...
rescue Couchbase::Error::NotFound => e
  ...
end

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 and our attempt to get raises a Couchbase::Error::NotFound error then our rescue block will be triggered. In which we're just outputting to the terminal again 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.

shell> ruby hello-world.rb

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

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

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

shell> 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> 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.