Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Install and Start Using the Ruby SDK with Couchbase Server

    +
    The Couchbase Ruby SDK allows you to connect to a Couchbase cluster from Ruby. The Ruby SDK includes high-performance native Ruby extensions to handle communicating to the cluster over Couchbase’s binary protocols.

    The Couchbase Ruby SDK 3.x is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for future Couchbase Server features like Collections and Scopes (available in Couchbase Server 7.0).

    Ruby SDK supports MRI Ruby versions 2.5, 2.6, and 2.7.

    Installing the SDK

    The source package is available through https://rubygems.org/gems/couchbase and can be installed with

    gem install couchbase

    In addition to rubygems.org, we also maintain official gem repositories, where we publish not only source version of the package, but also precompiled binaries for Linux and MacOS. Further details can be found on the Release Notes & Archives page.

    Hello Couchbase

    Couchbase uses Role Based Access Control (RBAC) to control access to resources. Here we will use the Full Admin role created during installation of the Couchbase Data Platform. For production client code, you will want to use more appropriate, restrictive settings, but here we want to get you up and running quickly. If you’re developing client code on the same VM or machine as the Couchbase Server, your URI can be localhost.

    require "couchbase"
include Couchbase # to avoid repeating module name
    options = Cluster::ClusterOptions.new
options.authenticate("Administrator", "password")
cluster = Cluster.connect("couchbase://localhost", options)

    The Cluster provides access to cluster-level operations like N1Ql queries, analytics, or full-text search. You will also find different management APIs on it. If you’re developing client code on the same VM or machine as the Couchbase Server, your connection string can be just localhost.

    If you are connecting to Couchbase Capella rather than a local Couchbase Server, then also refer to the Cloud section, below.

    Couchbase uses Role Based Access Control (RBAC) to control access to resources. For production client code, you will want to use more appropriate, restrictive settings  — but here we want to get you up and running quickly, so you can use the Full Admin role created during installation of the Couchbase Data Platform, in which case set Administrator as the username, and use the password that you defined in setting up your test Couchbase cluster.

    To access the KV (Key/Value) API or to query views, you need to open a Bucket:

    # get a bucket reference
bucket = cluster.bucket(bucket_name)

    If you installed the travel sample data bucket, substitute travel-sample for bucket_name.

    # get a user-defined collection reference
scope = bucket.scope("tenant_agent_00")
collection = scope.collection("users")

    The 3.2 SDK supports full integration with the Collections feature in the latest release of the Couchbase Data Platform, Couchbase Server 7.0. This brings complete support for Collections, allowing Documents to be grouped by purpose or theme, according to a specified Scope. Here we will use the users collection within the tenant_agent_00 scope from travel-sample bucket as an example.

    # Upsert Document
upsert_result = collection.upsert(
  "u:king_arthur",
  {
    "name" => "Arthur",
    "email" => "kingarthur@couchbase.com",
    "interests" => [
      "Holy Grails",
      "African Swallows"
    ]
  }
)
p cas: upsert_result.cas
#=> {:cas=>223322674373654}

# Get Document
get_result = collection.get("u:king_arthur")
p cas: get_result.cas,
  name: get_result.content["name"]
#=> {:cas=>223322674373654, :name=>"Arthur"}

    The code shows how you would use a named collection and scope. A named or default collection will provide the same functionality as bucket-level operations did in previous versions of Couchbase Server.

    KV Operations are described in detail on the KV Operations page. Now that you know the basics, you may wish to go straight to that page.

    You can also perform a N1QL query at the cluster level:

    result = cluster.query('SELECT "Hello World" AS greeting')
result.rows.each do |row|
  p row
  #=> {"greeting"=>"Hello World"}
end

    You can learn more about N1QL queries on the Query page. Other services (like analytics, search or views) work very similar to the two shown above. Please refer to their respective documentation sections to learn more.

    After completing operations, finish with (otherwise resources will be released by garbage collector):

    cluster.disconnect

    Cloud Connections

    For developing on Couchbase Capella, if you are not working from the same Availability Zone as your Capella instance, refer to the following:

    Additional Resources

    The API reference is generated for each release and can be found here. Older API references are linked from their respective sections in the Release Notes.

    Couchbase welcomes community contributions to the Ruby SDK. The Ruby SDK source code is available on GitHub.