Introducing the Couchbase Ruby client

Playing with Couchbase is easy.

For those first few steps, it’s all about simple CRUD operations on JSON documents: you’re putting JSON in, pulling it out again, making changes and deleting when you need to.

I’m going to write a short series of posts introducing the Couchbase Ruby client. In it, I’ll step through building a small app to keep track of Couchbase swag.

In this post, let’s get acquainted with Couchbase Server and the Ruby client.

Installing Couchbase and the Ruby client

If you haven’t already, get ahold of either the Community or Enterprise edition of Couchbase Server. Installation is straightforward and you can stick with the defaults for now.

For the SDK, we’ll need to install two things. The Ruby SDK is a wrapper around libcouchbase, Couchbase’s C client, so you’ll need to get that first.

Once you have that, install the couchbase gem:

{% highlight bash %}
$ sudo gem install couchbase
{% endhighlight %}

Connecting to Couchbase Server

Now we can write some code.

First up, let’s pull in the Ruby client and then connect to Couchbase:

{% highlight ruby %}
require ‘couchbase’

db = Couchbase.connect(:hostname => “localhost”)
{% endhighlight %}

That’s pretty self-explanatory: the database connection is loaded into the db object and the server is running locally. There a couple of other options we could’ve specified, but they’ll wait for another post.

Adding our first document

When we start importing the CSV file, it’ll show that each item in our warehouse has a:

  • product code
  • description
  • quantity.

Before we work the CSV, let’s try it manually.

The product code can act as our key: it is unique and reasonably short.

{% highlight ruby %}
key = “LAPTOPSLEEVE”
{% endhighlight %}

We’ll take the other two and create a hash:

{% highlight ruby %}
document = {“Description” => “Red Couchbase-branded laptop sleeve”,
“Quantity” => 91}
{% endhighlight %}

Now to write it into Couchbase we pass it to the db object:

{% highlight ruby %}
db.add(key, document)
{% endhighlight %}

Putting it all together we have:

{% highlight ruby linenos %}
require ‘couchbase’

db = Couchbase.connect(:hostname => “localhost”)

key = “LAPTOPSLEEVE”
document = {“Description” => “Red Couchbase-branded laptop sleeve”,
“Quantity” => 91}

db.add(key, document)
{% endhighlight %}

So, here’s what our script does:

  • connects to the Couchbase server
  • specifies a key name
  • creates a hash that the client will convert into the body of our JSON document
  • uses the add method to write both key and document into Couchbase.

Viewing your documents in the Couchbase web console

Open up the Couchbase web console to take a look.

In the top navigation, you’ll see Data Buckets. I’ll cover buckets in a later post but you can think of them as roughly equivalent to a database or collection that you might see in other database systems. For now, it’s just somewhere to put our data.

Click that Data Buckets link and you’ll see that Couchbase created a Default bucket for us at install time.

The Data Buckets page in Couchbase's web console

Press the Documents button and you’ll see our LAPTOPSLEEVE document.

The default bucket's document listing

It worked!

Adding versus setting

To get our laptop sleeve into Couchbase we used the add method.

Let’s try running our little script again. You’ll get an error from Couchbase that the key already exists.

If we want to write a document into Couchbase regardless of whether there’s already one using that key, we’ll need the set method.

Let’s try that instead:

{% highlight ruby linenos %}
require ‘couchbase’

db = Couchbase.connect(:hostname => “localhost”)

key = “LAPTOPSLEEVE”
document = {“Description” => “Black Couchbase-branded laptop sleeve”,
“Quantity” => 349}

db.set(key, document)
{% endhighlight %}

The set method silently overwrites any document already using our chosen key.

Refresh the documents view in the web console and you’ll see that we’ve changed the description and quantity for LAPTOPSLEEVE.

Our updated document

Reading and deleting

Reading the document is just as straightforward:

{% highlight ruby %}
db.get(“LAPTOPSLEEVE”)
{% endhighlight %}

You can probably guess how to delete a document:

{% highlight ruby %}
db.delete(“LAPTOPSLEEVE”)
{% endhighlight %}

Next time

We’ll tackle importing the CSV in the next post.