couchbase 3.4.0 → 3.4.1

data/ext/couchbase/couchbase/fmt/query_scan_consistency.hxx

@@ -21,6 +21,12 @@
 
 #include <fmt/core.h>
 
+/**
+ * Helper for fmtlib to format @ref couchbase::query_scan_consistency objects.
+ *
+ * @since 1.0.0
+ * @committed
+ */
 template<>
 struct fmt::formatter<couchbase::query_scan_consistency> {
     template<typename ParseContext>

data/ext/couchbase/couchbase/fmt/query_status.hxx

@@ -21,6 +21,12 @@
 
 #include <fmt/core.h>
 
+/**
+ * Helper for fmtlib to format @ref couchbase::query_status objects.
+ *
+ * @since 1.0.0
+ * @committed
+ */
 template<>
 struct fmt::formatter<couchbase::query_status> {
     template<typename ParseContext>

data/ext/couchbase/couchbase/fmt/retry_reason.hxx

@@ -21,6 +21,12 @@
 
 #include <fmt/core.h>
 
+/**
+ * Helper for fmtlib to format @ref couchbase::retry_reason objects.
+ *
+ * @since 1.0.0
+ * @committed
+ */
 template<>
 struct fmt::formatter<couchbase::retry_reason> {
     template<typename ParseContext>

data/ext/couchbase/couchbase/fmt/tls_verify_mode.hxx

@@ -21,6 +21,12 @@
 
 #include <fmt/core.h>
 
+/**
+ * Helper for fmtlib to format @ref couchbase::tls_verify_mode objects.
+ *
+ * @since 1.0.0
+ * @committed
+ */
 template<>
 struct fmt::formatter<couchbase::tls_verify_mode> {
     template<typename ParseContext>

data/ext/couchbase/couchbase/get_all_query_indexes_options.hxx

@@ -66,7 +66,8 @@ class get_all_query_indexes_options : public common_options<get_all_query_indexe
  * @uncommitted
  */
 
-using get_all_indexes_handler = std::function<void(couchbase::manager_error_context, std::vector<couchbase::management::query::index>)>;
+using get_all_query_indexes_handler =
+  std::function<void(couchbase::manager_error_context, std::vector<couchbase::management::query::index>)>;
 
 #ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
 namespace core
@@ -84,7 +85,7 @@ void
 initiate_get_all_query_indexes(std::shared_ptr<couchbase::core::cluster> core,
                                std::string bucket_name,
                                couchbase::get_all_query_indexes_options::built options,
-                               get_all_indexes_handler&& handler);
+                               get_all_query_indexes_handler&& handler);
 
 void
 initiate_get_all_query_indexes(std::shared_ptr<couchbase::core::cluster> core,
@@ -92,9 +93,9 @@ initiate_get_all_query_indexes(std::shared_ptr<couchbase::core::cluster> core,
                                couchbase::get_all_query_indexes_options::built options,
                                query_context query_ctx,
                                std::string collection_name,
-                               get_all_indexes_handler&& handler);
+                               get_all_query_indexes_handler&& handler);
 
 #endif
 } // namespace impl
 } // namespace core
-} // namespace couchbase
+} // namespace couchbase

data/ext/couchbase/couchbase/query_index_manager.hxx

@@ -59,10 +59,12 @@ class query_index_manager
      * @since 1.0.0
      * @committed
      */
-    void get_all_indexes(std::string bucket_name, const get_all_query_indexes_options& options, get_all_indexes_handler&& handler) const
+    void get_all_indexes(std::string bucket_name,
+                         const get_all_query_indexes_options& options,
+                         get_all_query_indexes_handler&& handler) const
     {
         return core::impl::initiate_get_all_query_indexes(
-          core_, std::move(bucket_name), options.build(), std::forward<get_all_indexes_handler>(handler));
+          core_, std::move(bucket_name), options.build(), std::forward<get_all_query_indexes_handler>(handler));
     }
     [[nodiscard]] auto get_all_indexes(std::string bucket_name, const get_all_query_indexes_options& options) const
       -> std::future<std::pair<manager_error_context, std::vector<couchbase::management::query::index>>>

data/ext/couchbase/couchbase/scope.hxx

@@ -121,7 +121,7 @@ class scope
      * @since 1.0.0
      * @committed
      */
-    [[nodiscard]] auto query(std::string statement, const query_options& options) const
+    [[nodiscard]] auto query(std::string statement, const query_options& options = {}) const
       -> std::future<std::pair<query_error_context, query_result>>
     {
         auto barrier = std::make_shared<std::promise<std::pair<query_error_context, query_result>>>();

data/ext/couchbase/couchbase/subdoc/array_add_unique.hxx

@@ -71,7 +71,9 @@ class array_add_unique
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     array_add_unique(std::string path, std::vector<std::byte> value)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/array_append.hxx

@@ -70,7 +70,9 @@ class array_append
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     array_append(std::string path, std::vector<std::vector<std::byte>> values)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/array_insert.hxx

@@ -71,7 +71,9 @@ class array_insert
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     array_insert(std::string path, std::vector<std::vector<std::byte>> values)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/array_prepend.hxx

@@ -71,7 +71,9 @@ class array_prepend
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     array_prepend(std::string path, std::vector<std::vector<std::byte>> values)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/count.hxx

@@ -54,7 +54,9 @@ class count
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::lookup_in_specs;
+#endif
 
     explicit count(std::string path)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/counter.hxx

@@ -69,7 +69,9 @@ class counter
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     counter(std::string path, std::int64_t value)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/exists.hxx

@@ -54,7 +54,9 @@ class exists
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::lookup_in_specs;
+#endif
 
     explicit exists(std::string path)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/get.hxx

@@ -56,7 +56,9 @@ class get
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::lookup_in_specs;
+#endif
 
     explicit get(std::string path)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/insert.hxx

@@ -71,7 +71,9 @@ class insert
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     insert(std::string path, std::vector<std::byte> value)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/remove.hxx

@@ -54,7 +54,9 @@ class remove
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     explicit remove(std::string path)
       : path_(std::move(path))

data/ext/couchbase/couchbase/subdoc/replace.hxx

@@ -56,7 +56,9 @@ class replace
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     replace(std::string path, std::vector<std::byte> value)
       : path_(std::move(path))
@@ -86,4 +88,4 @@ class replace
     bool expand_macro_{ false };
 };
 } // namespace subdoc
-} // namespace couchbase
+} // namespace couchbase

data/ext/couchbase/couchbase/subdoc/upsert.hxx

@@ -71,7 +71,9 @@ class upsert
     }
 
   private:
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
     friend couchbase::mutate_in_specs;
+#endif
 
     upsert(std::string path, std::vector<std::byte> value)
       : path_(std::move(path))

data/ext/couchbase/couchbase/transaction_op_error_context.hxx

@@ -46,13 +46,13 @@ class transaction_op_error_context
     }
 
     /**
-     * The error_code associated with this error context.   This will always be a @ref transaction_op_error_code
+     * The error_code associated with this error context.
      *
      * Note that some query errors are not _transaction_ errors, so this error code will be 0, but there will be
-     * a @ref transaction_op_error_code#cause() with a query_error_context in it.  These errors do not rollback a
+     * a @ref cause() with a @ref query_error_context in it.  These errors do not rollback a
      * transaction.   If you want to roll it back, raise an exception.
      *
-     * @return a transaction_op_error_code, if any.
+     * @return a error code, if any.
      */
     [[nodiscard]] std::error_code ec() const
     {
@@ -60,7 +60,7 @@ class transaction_op_error_context
     }
 
     /**
-     * The underlying cause of this error.   This can be either a @ref key_value_error_code or a @ref query_error_context.
+     * The underlying cause of this error.   This can be either a @ref key_value_error_context or a @ref query_error_context.
      *
      * @return the error_context associated with the underlying cause of this error.
      */

data/ext/couchbase/couchbase/transactions/transaction_get_result.hxx

@@ -24,36 +24,31 @@
 #include <couchbase/result.hxx>
 #include <couchbase/transaction_op_error_context.hxx>
 
+// forward declarations...
+namespace couchbase::core::transactions
+{
+class transaction_get_result;
+class transaction_links;
+class document_metadata;
+} // namespace couchbase::core::transactions
+
 namespace couchbase::transactions
 {
 
-class transaction_get_result : public result
+class transaction_get_result
 {
-  protected:
-    std::string bucket_{};
-    std::string scope_{};
-    std::string collection_{};
-    std::string key_{};
-    std::vector<std::byte> content_{};
+    friend class couchbase::core::transactions::transaction_get_result;
 
-  public:
-    transaction_get_result() = default;
-
-    transaction_get_result(std::string bucket,
-                           std::string scope,
-                           std::string collection,
-                           std::string key,
-                           couchbase::cas cas,
-                           std::vector<std::byte> content)
-      : result(cas)
-      , bucket_(std::move(bucket))
-      , scope_(std::move(scope))
-      , collection_(std::move(collection))
-      , key_(std::move(key))
-      , content_(std::move(content))
+  private:
+    std::shared_ptr<couchbase::core::transactions::transaction_get_result> base_{};
+
+    transaction_get_result(std::shared_ptr<couchbase::core::transactions::transaction_get_result> base)
+      : base_(base)
     {
     }
 
+  public:
+    transaction_get_result();
     /**
      * Content of the document.
      *
@@ -62,7 +57,7 @@ class transaction_get_result : public result
     template<typename Content>
     [[nodiscard]] Content content() const
     {
-        return codec::tao_json_serializer::deserialize<Content>(content_);
+        return codec::tao_json_serializer::deserialize<Content>(content());
     }
 
     /**
@@ -70,64 +65,54 @@ class transaction_get_result : public result
      *
      * @return content
      */
-    [[nodiscard]] const std::vector<std::byte>& content() const
-    {
-        return content_;
-    }
+    [[nodiscard]] const std::vector<std::byte>& content() const;
+
     /**
      * Copy content into document
      * @param content
      */
-    void content(std::vector<std::byte> content)
-    {
-        content_ = std::move(content);
-    }
+    void content(std::vector<std::byte> content);
+
     /**
      * Move content into document
      *
      * @param content
      */
-    void content(std::vector<std::byte>&& content)
-    {
-        content_ = std::move(content);
-    }
+    void content(std::vector<std::byte>&& content);
 
     /**
      * Get document id.
      *
      * @return the id of this document.
      */
-    [[nodiscard]] const std::string key() const
-    {
-        return key_;
-    }
+    [[nodiscard]] const std::string key() const;
 
     /**
      * Get the name of the bucket this document is in.
      *
      * @return name of the bucket which contains the document.
      */
-    [[nodiscard]] const std::string bucket() const
-    {
-        return bucket_;
-    }
+    [[nodiscard]] const std::string bucket() const;
+
     /**
      * Get the name of the scope this document is in.
      *
      * @return name of the scope which contains the document.
      */
-    [[nodiscard]] const std::string scope() const
-    {
-        return scope_;
-    }
+    [[nodiscard]] const std::string scope() const;
+
     /**
      * Get the name of the collection this document is in.
      *
      * @return name of the collection which contains the document.
      */
-    [[nodiscard]] const std::string collection() const
-    {
-        return collection_;
-    }
+    [[nodiscard]] const std::string collection() const;
+
+    /**
+     * Get the CAS fot this document
+     *
+     * @return the CAS of the document.
+     */
+    [[nodiscard]] const couchbase::cas cas() const;
 };
 } // namespace couchbase::transactions

data/ext/couchbase/couchbase/transactions/transactions_config.hxx

@@ -115,7 +115,7 @@ class transactions_config
     /**
      * @brief Set the expiration time for transactions.
      *
-     * @param duration desired expiration for transactions. see @expiration_time().
+     * @param duration desired expiration for transactions. see @ref expiration_time().
      * @return reference to this, so calls can be chained.
      */
     template<typename T>

data/ext/couchbase/test/CMakeLists.txt

@@ -39,3 +39,5 @@ transaction_test(transaction_public_async_api)
 unit_test(transaction_logging)
 unit_test(transaction_utils)
 unit_test(waitable_op_list)
+
+integration_test(examples)

data/ext/couchbase/test/test_integration_examples.cxx

@@ -0,0 +1,141 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2023-Present 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
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#include "test_helper_integration.hxx"
+
+#include <couchbase/cluster.hxx>
+#include <couchbase/fmt/cas.hxx>
+#include <couchbase/fmt/mutation_token.hxx>
+
+#include <tao/json.hpp>
+
+namespace start_using
+{
+//! [start-using]
+#include <couchbase/cluster.hxx>
+#include <couchbase/fmt/cas.hxx>
+#include <couchbase/fmt/mutation_token.hxx>
+
+#include <tao/json.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] };
+    std::string username{ argv[2] };
+    std::string password{ argv[3] };
+    std::string bucket_name{ "travel-sample" };
+
+    // run IO context on separate thread
+    asio::io_context io;
+    auto guard = asio::make_work_guard(io);
+    std::thread io_thread([&io]() { io.run(); });
+
+    auto options = couchbase::cluster_options(username, password);
+    // customize through the 'options'.
+    // For example, optimize timeouts for WAN
+    options.apply_profile("wan_development");
+
+    auto [cluster, ec] = couchbase::cluster::connect(io, connection_string, options).get();
+    if (ec) {
+        fmt::print("unable to connect to the cluster: {}\n", ec.message());
+        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");
+
+    {
+        // upsert document
+        auto [ctx, upsert_result] = collection.upsert("my-document", tao::json::value{ { "name", "mike" } }).get();
+        if (ctx.ec()) {
+            fmt::print("unable to upsert the document \"{}\": {}\n", ctx.id(), ctx.ec().message());
+            return 1;
+        }
+        fmt::print("saved document \"{}\", cas={}, token={}\n", ctx.id(), upsert_result.cas(), upsert_result.mutation_token().value());
+    }
+
+    {
+        // get document
+        auto [ctx, get_result] = collection.get("my-document").get();
+        if (ctx.ec()) {
+            fmt::print("unable to get the document \"{}\": {}\n", ctx.id(), ctx.ec().message());
+            return 1;
+        }
+        auto name = get_result.content_as<tao::json::value>()["name"].get_string();
+        fmt::print("retrieved document \"{}\", name=\"{}\"\n", ctx.id(), name);
+    }
+
+    {
+        // N1QL query
+        auto inventory_scope = bucket.scope("inventory");
+        auto [ctx, query_result] = inventory_scope.query("SELECT * FROM airline WHERE id = 10").get();
+        if (ctx.ec()) {
+            fmt::print("unable to perform query: {}, ({}, {})\n", ctx.ec().message(), ctx.first_error_code(), ctx.first_error_message());
+            return 1;
+        }
+        for (const auto& row : query_result.rows_as_json()) {
+            fmt::print("row: {}\n", tao::json::to_string(row));
+        }
+    }
+
+    // close cluster connection
+    cluster.close();
+    guard.reset();
+
+    io_thread.join();
+    return 0;
+}
+
+/*
+
+$ ./start_using couchbase://127.0.0.1 Administrator password
+saved document "my-document", cas=17486a1722b20000
+retrieved document "my-document", name="mike"
+row: {"airline":{"callsign":"MILE-AIR","country":"United States","iata":"Q5","icao":"MLA","id":10,"name":"40-Mile Air","type":"airline"}}
+
+ */
+//! [start-using]
+
+} // namespace start_using
+
+TEST_CASE("example: start using", "[integration]")
+{
+    test::utils::integration_test_guard integration;
+    if (!integration.cluster_version().supports_collections()) {
+        return;
+    }
+
+    const auto env = test::utils::test_context::load_from_environment();
+    const char* argv[] = {
+        "start_using", // name of the "executable"
+        env.connection_string.c_str(),
+        env.username.c_str(),
+        env.password.c_str(),
+    };
+
+    REQUIRE(start_using::main(4, argv) == 0);
+}