Couchbase Ruby Client

This repository contains the third generation of the official Couchbase SDK for Ruby (aka. SDKv3)

Support and Feedback

If you find an issue, please file it in our JIRA issue tracker. Also you are always welcome on our forum.

Please attach version information to ticket/post. To obtain this information use the following command:

$ ruby -r couchbase -e 'p Couchbase::VERSION'


The library tested with the MRI 2.5, 2.6 and 2.7. Supported platforms are Linux and MacOS.

Add this line to your application's Gemfile:

# version (does not have precompiled binaries)
gem "couchbase", "3.0.2"

# use official repository
gem "couchbase", "3.0.2", :source => ""

## precompiled binaries (uncomment line with effective ABI version of ruby)
# gem "couchbase", "3.0.2", :platforms => :mri_27, :source => ""
# gem "couchbase", "3.0.2", :platforms => :mri_26, :source => ""
# gem "couchbase", "3.0.2", :platforms => :mri_25, :source => ""

And then execute:

$ bundle install

Or install it yourself as:

$ gem install couchbase

For some platforms we precompile binary packages. When, for some reason, binary package cannot be used, pass --platform=ruby to gem install command (or check specific_platform and force_ruby_platform options of Bundler). In latter case, see Development section for build dependencies.


Here is a basic steps demonstrating basic operations with data:

require "couchbase"
include Couchbase # include Couchbase module for brevity

# initialize library
cluster = Cluster.connect("couchbase://", "Administrator", "password")

# open bucket and collection for data operations
bucket = cluster.bucket("my_bucket")
collection = bucket.default_collection

# update or insert the document
res = collection.upsert("foo", {"bar" => 42})
#=> 22120998714646

# retrieve document from the collection
res = collection.get("foo")
#=> 22120998714646
#=> {"bar"=>42}

# remove document
res = collection.remove("foo")
#=> 47891154812182

# fetch top-3 cities by number of hotels in the collection
res = cluster.query("
          SELECT city, COUNT(*) AS cnt FROM `travel-sample`
          WHERE type = $type
          GROUP BY city
          ORDER BY cnt DESC
          LIMIT 3",
        Options::Query(named_parameters: {type: "hotel"}, metrics: true))
res.rows.each do |row|
  p row
#=> {"city"=>"San Francisco", "cnt"=>132}
#   {"city"=>"London", "cnt"=>67}
#   {"city"=>"Paris", "cnt"=>64}


After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

Part of the library is written in C++, and requires both C and C++ compilers installed on the system. To configure build environment, it uses cmake. When these tools installed, the build process is easy:

$ rake compile

Generate Documentation

To generate documentation yard library is highly recommended.

$ gem install yard

The following steps will generate API reference for selected git tag:

$ rake doc

Now the API reference is accessible using web browser (where VERSION is current version of the SDK)

$ firefox doc/couchbase-ruby-client-VERSION/index.html


The gem is available as open source under the terms of the Apache2 License.

Copyright 2011-2020 Couchbase, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.