Couchbase C++ SDK

Note

You may read about related Couchbase software at https://docs.couchbase.com/

Start Using

The following example shows the most basic usage of the library. It performs the following operations:

• [1] connect to local cluster (location and credentials given in program arguments),
• [2] persists document to the collection using couchbase::collection::upsert(),
• [3] retrieves document back with couchbase::collection::get(), extracts content as generic JSON value, and prints one of the fields,
• [4] performs N1QL query with couchbase::scope::query() and prints the result.
• [5] output results obtained in [4] using custom type defined in [6]
• [7] closes the cluster and deallocate resources

#include <couchbase/cluster.hxx>
#include <couchbase/fmt/cas.hxx>
#include <couchbase/fmt/mutation_token.hxx>
 
#include <tao/json.hpp>
#include <tao/json/contrib/traits.hpp>
 
int
main(int argc, const char* argv[])
{
  if (argc != 4) {
    fmt::print("USAGE: ./start_using couchbase://127.0.0.1 Administrator password\n");
    return 1;
  }
 
  std::string connection_string{ argv[1] }; // "couchbase://127.0.0.1"
  std::string username{ argv[2] };          // "Administrator"
  std::string password{ argv[3] };          // "password"
  std::string bucket_name{ "travel-sample" };
 
  auto options = couchbase::cluster_options(username, password);
  // customize through the 'options'.
  // For example, optimize timeouts for WAN
  options.apply_profile("wan_development");
 
  // [1] connect to cluster using the given connection string and the options
  auto [connect_err, cluster] = couchbase::cluster::connect(connection_string, options).get();
  if (connect_err) {
    fmt::print("unable to connect to the cluster: {}\n", connect_err);
    return 1;
  }
 
  // get a bucket reference
  auto bucket = cluster.bucket(bucket_name);
 
  // get a user-defined collection reference
  auto scope = bucket.scope("tenant_agent_00");
  auto collection = scope.collection("users");
 
  { // [2] upsert document
    std::string doc_id = "my-document";
    auto [err, upsert_result] =
      collection.upsert(doc_id, tao::json::value{ { "name", "mike" } }).get();
    if (err.ec()) {
      fmt::print("unable to upsert the document \"{}\": {}\n", doc_id, err);
      return 1;
    }
    fmt::print("saved document \"{}\", cas={}, token={}\n",
               doc_id,
               upsert_result.cas(),
               upsert_result.mutation_token().value());
  }
 
  { // [3] get document
    std::string doc_id = "my-document";
    auto [err, get_result] = collection.get(doc_id).get();
    if (err.ec()) {
      fmt::print("unable to get the document \"{}\": {}\n", doc_id, err);
      return 1;
    }
    auto name = get_result.content_as<tao::json::value>()["name"].get_string();
    fmt::print("retrieved document \"{}\", name=\"{}\"\n", doc_id, name);
  }
 
  { // [4] N1QL query
    auto inventory_scope = bucket.scope("inventory");
    // Select first 5 hotels from US or UK, that describe themselves as cheap
    // and order them by overall rating.
    std::string query{ R"(
        SELECT META(h).id, h AS doc,
               AVG(r.ratings.Overall) AS avg_rating
        FROM hotel h
        UNNEST h.reviews r
        WHERE h.country IN $1 AND h.description LIKE "%cheap%"
        GROUP BY META(h).id, h
        ORDER BY avg_rating DESC
        LIMIT 5;
    )" };
    auto query_options = couchbase::query_options{}.positional_parameters(
      std::vector{ "United States", "United Kingdom" });
    auto [error, query_result] = inventory_scope.query(query, query_options).get();
    if (error) {
      fmt::print("unable to perform query: {}\n", error.ctx().to_json());
      return 1;
    }
    fmt::println("{:<15} {:<15} {:>10} {:<30}", "ID", "Country", "Rating", "Hotel");
    for (auto& row : query_result.rows_as_json()) {
      fmt::println("{:<15} {:<15} {:>10.2f} {:<30}",
                   row["id"].as<std::string>(),
                   row["doc"]["country"].as<std::string>(),
                   row["avg_rating"].as<double>(),
                   row["doc"]["title"].as<std::string>());
    }
 
    // [5] iterate over results using custom type
    fmt::println("{:<15} {:<15} {:>10} {:<30}", "ID", "Country", "Rating", "Hotel");
    for (const auto& row : query_result.rows_as<couchbase::codec::tao_json_serializer, hotel>()) {
      fmt::println(
        "{:<15} {:<15} {:>10.2f} {:<30}", row.id, row.country, row.average_rating, row.name);
    }
  }
 
  // [7] close cluster connection
  cluster.close().get();
  return 0;
}
 
/*
 
$ ./start_using couchbase://127.0.0.1 Administrator password
saved document "my-document", cas=17ed9f687ee90000, token=travel-sample:110:101634532779186:101
retrieved document "my-document", name="mike"
ID              Country             Rating Hotel
hotel_26169     United States         4.75 San Francisco/Twin Peaks-Lake Merced
hotel_26499     United States         4.60 Santa Monica
hotel_3616      United Kingdom        4.57 Birmingham (England)
hotel_7387      United States         4.50 Death Valley National Park
hotel_25588     United States         4.44 San Francisco/Civic Center-Tenderloin
 
 */

// [6] definition of the custom type and its decoder
struct hotel {
  std::string id{};
  std::string name{};
  std::string country{};
  double average_rating{};
};
 
template<>
struct tao::json::traits<hotel> {
  template<template<typename...> class Traits>
  static auto as(const tao::json::basic_value<Traits>& v) -> hotel
  {
    hotel result;
    auto object = v.get_object();
    result.id = object["id"].template as<std::string>();
    result.average_rating = object["avg_rating"].template as<double>();
    result.name = object["doc"]["title"].template as<std::string>();
    result.country = object["doc"]["country"].template as<std::string>();
    return result;
  }
};

Using Transactions

Next example shows transactions API. Read more details in couchbase::transactions::transactions

• [1] connect to cluster using the given connection string and the options
• [2] persist three documents to the default collection of bucket "default"
• [3] blocking transaction
  • [3.1] closure argument to couchbase::transactions::transactions::run method encapsulates logic, that has to be run in transaction
  • [3.2] get document
  • [3.4] replace document's content
  • [3.5] check the overall status of the transaction
• [4] asynchronous transaction
  • [4.1] create promise to retrieve result from the transaction
  • [4.2] closure argument to couchbase::transactions::transactions::run method encapsulates logic, that has to be run in transaction
  • [4.3] get document
  • [4.4] replace document's content
  • [4.5] second closure argument to couchbase::transactions::transactions::run represents transaction completion logic
• [5] close cluster connection

#include <couchbase/cluster.hxx>
#include <couchbase/fmt/cas.hxx>
 
#include <tao/json.hpp>
 
int
main(int argc, const char* argv[])
{
  if (argc != 4) {
    fmt::print("USAGE: ./blocking-txn couchbase://127.0.0.1 Administrator password\n");
    return 1;
  }
 
  int retval = 0;
 
  const std::string connection_string{ argv[1] };
  const std::string username{ argv[2] };
  const std::string password{ argv[3] };
 
  auto options = couchbase::cluster_options(username, password);
  // customize through the 'options'.
  // For example, optimize timeouts for WAN
  options.apply_profile("wan_development");
 
  // [1] connect to cluster using the given connection string and the options
  auto [connect_err, cluster] = couchbase::cluster::connect(connection_string, options).get();
  if (connect_err) {
    fmt::print("unable to connect to the cluster: {}\n", connect_err);
    return 1;
  }
 
  // [2] persist three documents to the default collection of bucket "default"
  auto collection = cluster.bucket("default").default_collection();
  constexpr auto id_1 = "my-doc_1";
  constexpr auto id_2 = "my_doc_2";
  constexpr auto id_3 = "my_doc_3";
  const tao::json::value content = { { "some", "content" } };
 
  for (const auto& id : { id_1, id_2, id_3 }) {
    if (auto [err, res] = collection.upsert(id, content).get(); err.ec()) {
      fmt::print(
        stderr, "upsert \"{}\" failed before starting transaction: {}\n", id, err.ec().message());
      return 1;
    }
  }
 
  { // [3] blocking transaction
    auto [tx_err, tx_res] = cluster.transactions()->run(
      // [3.1] closure argument to run() method encapsulates logic, that has to be run in
      // transaction
      [=](std::shared_ptr<couchbase::transactions::attempt_context> ctx) -> couchbase::error {
        // [3.2] get document
        auto [err_ctx, doc] = ctx->get(collection, id_1);
        if (err_ctx.ec()) {
          fmt::print(stderr, "failed to get document \"{}\": {}\n", id_1, err_ctx.ec().message());
          // [3.3] don't continue the transaction logic
          return {};
        }
        // [3.4] replace document's content
        ctx->replace(doc, tao::json::value{ { "some", "other content" } });
        return {};
      });
    // [3.5] check the overall status of the transaction
    if (tx_err.ec()) {
      fmt::print(stderr,
                 "error in transaction {}, cause: {}\n",
                 tx_err.ec().message(),
                 tx_err.cause().has_value() ? tx_err.cause().value().ec().message() : "");
      retval = 1;
    } else {
      fmt::print("transaction {} completed successfully\n", tx_res.transaction_id);
    }
  }
 
  { // [4] asynchronous transaction
    // [4.1] create promise to retrieve result from the transaction
    auto barrier = std::make_shared<std::promise<std::error_code>>();
    auto f = barrier->get_future();
    cluster.transactions()->run(
      // [4.2] closure argument to run() method encapsulates logic, that has to be run in
      // transaction
      [=](std::shared_ptr<couchbase::transactions::async_attempt_context> ctx) -> couchbase::error {
        // [4.3] get document
        ctx->get(collection, id_1, [=](auto err_ctx_1, auto doc) {
          if (err_ctx_1.ec()) {
            fmt::print(
              stderr, "failed to get document \"{}\": {}\n", id_1, err_ctx_1.ec().message());
            return;
          }
          // [4.4] replace document's content
          ctx->replace(doc,
                       tao::json::value{ { "some", "other async content" } },
                       [=](auto err_ctx_2, auto /*res*/) {
                         if (err_ctx_2.ec()) {
                           fmt::print(stderr,
                                      "error replacing content in doc {}: {}\n",
                                      id_1,
                                      err_ctx_2.ec().message());
                         } else {
                           fmt::print("successfully replaced: {}\n", id_1);
                         }
                       });
        });
        ctx->get(collection, id_2, [=](auto err_ctx_1, auto doc) {
          if (err_ctx_1.ec()) {
            fmt::print("error getting doc {}: {}", id_2, err_ctx_1.ec().message());
            return;
          }
          ctx->replace(doc,
                       tao::json::value{ { "some", "other async content" } },
                       [=](auto err_ctx_2, auto /*res*/) {
                         if (err_ctx_2.ec()) {
                           fmt::print(stderr,
                                      "error replacing content in doc {}: {}\n",
                                      id_2,
                                      err_ctx_2.ec().message());
                         } else {
                           fmt::print("successfully replaced: {}\n", id_2);
                         }
                       });
        });
        ctx->get(collection, id_3, [=](auto err_ctx_1, auto doc) {
          if (err_ctx_1.ec()) {
            fmt::print(stderr, "error getting doc {}: {}\n", id_3, err_ctx_1.ec().message());
            return;
          }
          ctx->replace(doc,
                       tao::json::value{ { "some", "other async content" } },
                       [=](auto err_ctx_2, auto /*res*/) {
                         if (err_ctx_2.ec()) {
                           fmt::print(stderr,
                                      "error replacing content in doc {}: {}\n",
                                      id_3,
                                      err_ctx_2.ec().message());
                         } else {
                           fmt::print("successfully replaced: {}\n", id_3);
                         }
                       });
        });
        return {};
      },
      // [4.5], second closure represents transaction completion logic
      [barrier](auto tx_err, auto tx_res) {
        if (tx_err.ec()) {
          fmt::print(stderr,
                     "error in async transaction {}, {}\n",
                     tx_res.transaction_id,
                     tx_err.ec().message());
        }
        barrier->set_value(tx_err.ec());
      });
    if (auto async_err = f.get()) {
      fmt::print(stderr, "received async error from future: message - {}\n", async_err.message());
      retval = 1;
    }
  }
 
  // [5], close cluster connection
  cluster.close().get();
  return retval;
}
 

See also simple class that implements an operation in fictional game backend: game_server.cxx (and its asynchronous version in async_game_server.cxx)