couchbase 4.2.1 → 4.2.3

package/deps/couchbase-cxx-client/test/test_integration_analytics.cxx

@@ -17,7 +17,7 @@
 
 #include "core/operations/management/analytics.hxx"
 #include "core/operations/management/collection_create.hxx"
-#include "core/operations/management/scope_create.hxx"
+#include "core/operations/management/collections.hxx"
 #include "test_helper_integration.hxx"
 
 TEST_CASE("integration: analytics query")
@@ -78,7 +78,7 @@ TEST_CASE("integration: analytics query")
         REQUIRE(test::utils::wait_until([&]() {
             couchbase::core::operations::analytics_request req{};
             req.statement = fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = ?)", dataset_name);
-            req.positional_parameters.emplace_back(couchbase::core::json_string(couchbase::core::utils::json::generate(test_value)));
+            req.positional_parameters.emplace_back(couchbase::core::utils::json::generate(test_value));
             resp = test::utils::execute(integration.cluster, req);
             return resp.rows.size() == 1;
         }));
@@ -130,10 +130,30 @@ TEST_CASE("integration: analytics query")
 
     SECTION("consistency")
     {
-        couchbase::core::operations::analytics_request req{};
-        req.statement = fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = "{}")", dataset_name, test_value);
-        req.scan_consistency = couchbase::core::analytics_scan_consistency::request_plus;
-        auto resp = test::utils::execute(integration.cluster, req);
+        couchbase::core::operations::analytics_response resp{};
+        CHECK(test::utils::wait_until([&]() {
+            /*
+             * In consistency test, always do fresh mutation
+             */
+            test_value = test::utils::uniq_id("value");
+            value = couchbase::core::utils::json::generate({ { "testkey", test_value } });
+            {
+                auto id = couchbase::core::document_id(integration.ctx.bucket, "_default", "_default", key);
+                couchbase::core::operations::upsert_request req{ id, couchbase::core::utils::to_binary(value) };
+                REQUIRE_SUCCESS(test::utils::execute(integration.cluster, req).ctx.ec());
+            }
+
+            couchbase::core::operations::analytics_request req{};
+            req.statement = fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = "{}")", dataset_name, test_value);
+            req.scan_consistency = couchbase::core::analytics_scan_consistency::request_plus;
+            resp = test::utils::execute(integration.cluster, req);
+            /* Analytics might give us code 23027, ignore it here
+             *
+             * "errors": [{"code": 23027, "msg": "Bucket default on link Default.Local is not connected"} ],
+             */
+            return resp.ctx.first_error_code != 23027;
+        }));
+
         REQUIRE_SUCCESS(resp.ctx.ec);
         REQUIRE(resp.rows.size() == 1);
         REQUIRE(resp.rows[0] == value);
@@ -185,13 +205,15 @@ TEST_CASE("integration: analytics scope query")
         REQUIRE(created);
     }
 
-    {
-        couchbase::core::operations::analytics_request req{};
-        req.statement =
-          fmt::format("ALTER COLLECTION `{}`.`{}`.`{}` ENABLE ANALYTICS", integration.ctx.bucket, scope_name, collection_name);
-        auto resp = test::utils::execute(integration.cluster, req);
-        REQUIRE_SUCCESS(resp.ctx.ec);
-    }
+    CHECK(test::utils::wait_until(
+      [&]() {
+          couchbase::core::operations::analytics_request req{};
+          req.statement =
+            fmt::format("ALTER COLLECTION `{}`.`{}`.`{}` ENABLE ANALYTICS", integration.ctx.bucket, scope_name, collection_name);
+          auto resp = test::utils::execute(integration.cluster, req);
+          return !resp.ctx.ec;
+      },
+      std::chrono::minutes{ 5 }));
 
     auto key = test::utils::uniq_id("key");
     auto test_value = test::utils::uniq_id("value");
@@ -259,3 +281,257 @@ TEST_CASE("unit: analytics query")
         REQUIRE(http_req.headers.find("analytics-priority") == http_req.headers.end());
     }
 }
+
+TEST_CASE("integration: public API analytics query")
+{
+    test::utils::integration_test_guard integration;
+
+    if (!integration.cluster_version().supports_analytics()) {
+        return;
+    }
+
+    auto cluster = couchbase::cluster(integration.cluster);
+    auto bucket = cluster.bucket(integration.ctx.bucket);
+    auto collection = bucket.default_collection();
+
+    auto dataset_name = test::utils::uniq_id("dataset");
+
+    {
+        couchbase::core::operations::management::analytics_dataset_create_request req{};
+        req.dataset_name = dataset_name;
+        req.bucket_name = integration.ctx.bucket;
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE_SUCCESS(resp.ctx.ec);
+    }
+
+    {
+        couchbase::core::operations::management::analytics_link_connect_request req{};
+        req.force = true;
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE_SUCCESS(resp.ctx.ec);
+    }
+
+    auto key = test::utils::uniq_id("key");
+    auto test_value = test::utils::uniq_id("value");
+    tao::json::value document = {
+        { "testkey", test_value },
+    };
+    {
+        auto [ctx, resp] = collection.upsert(key, document).get();
+        REQUIRE_SUCCESS(ctx.ec());
+    }
+
+    SECTION("simple query")
+    {
+        couchbase::analytics_result resp{};
+        couchbase::analytics_error_context ctx{};
+        CHECK(test::utils::wait_until([&]() {
+            std::tie(ctx, resp) =
+              cluster.analytics_query(fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = "{}")", dataset_name, test_value))
+                .get();
+            return !ctx.ec() && resp.meta_data().metrics().result_count() == 1;
+        }));
+        REQUIRE_SUCCESS(ctx.ec());
+        REQUIRE_FALSE(resp.meta_data().request_id().empty());
+        REQUIRE_FALSE(resp.meta_data().client_context_id().empty());
+        REQUIRE(resp.meta_data().status() == couchbase::analytics_status::success);
+        auto rows = resp.rows_as_json();
+        REQUIRE(rows.size() == 1);
+        REQUIRE(rows[0] == document);
+    }
+
+    SECTION("positional params")
+    {
+        couchbase::analytics_result resp{};
+        couchbase::analytics_error_context ctx{};
+        CHECK(test::utils::wait_until([&]() {
+            std::tie(ctx, resp) = cluster
+                                    .analytics_query(fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = ?)", dataset_name),
+                                                     couchbase::analytics_options{}.positional_parameters(test_value))
+                                    .get();
+            return !ctx.ec() && resp.meta_data().metrics().result_count() == 1;
+        }));
+        REQUIRE_SUCCESS(ctx.ec());
+        auto rows = resp.rows_as_json();
+        REQUIRE(rows.size() == 1);
+        REQUIRE(rows[0] == document);
+    }
+
+    SECTION("named params")
+    {
+        couchbase::analytics_result resp{};
+        couchbase::analytics_error_context ctx{};
+        CHECK(test::utils::wait_until([&]() {
+            std::tie(ctx, resp) =
+              cluster
+                .analytics_query(fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = $testkey)", dataset_name),
+                                 couchbase::analytics_options{}.named_parameters(std::pair{ "testkey", test_value }))
+                .get();
+            return !ctx.ec() && resp.meta_data().metrics().result_count() == 1;
+        }));
+        REQUIRE_SUCCESS(ctx.ec());
+        auto rows = resp.rows_as_json();
+        REQUIRE(rows.size() == 1);
+        REQUIRE(rows[0] == document);
+    }
+
+    SECTION("named params preformatted")
+    {
+        couchbase::analytics_result resp{};
+        couchbase::analytics_error_context ctx{};
+        CHECK(test::utils::wait_until([&]() {
+            std::tie(ctx, resp) =
+              cluster
+                .analytics_query(fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = $testkey)", dataset_name),
+                                 couchbase::analytics_options{}.encoded_named_parameters(
+                                   { { "testkey", couchbase::core::utils::json::generate_binary(test_value) } }))
+                .get();
+            return !ctx.ec() && resp.meta_data().metrics().result_count() == 1;
+        }));
+        REQUIRE_SUCCESS(ctx.ec());
+        auto rows = resp.rows_as_json();
+        REQUIRE(rows.size() == 1);
+        REQUIRE(rows[0] == document);
+    }
+
+    SECTION("raw")
+    {
+        couchbase::analytics_result resp{};
+        couchbase::analytics_error_context ctx{};
+        CHECK(test::utils::wait_until([&]() {
+            std::tie(ctx, resp) =
+              cluster
+                .analytics_query(fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = $testkey)", dataset_name),
+                                 couchbase::analytics_options{}.raw("$testkey", test_value))
+                .get();
+            return !ctx.ec() && resp.meta_data().metrics().result_count() == 1;
+        }));
+        REQUIRE_SUCCESS(ctx.ec());
+        auto rows = resp.rows_as_json();
+        REQUIRE(rows.size() == 1);
+        REQUIRE(rows[0] == document);
+    }
+
+    SECTION("consistency")
+    {
+        couchbase::analytics_result resp{};
+        couchbase::analytics_error_context ctx{};
+        CHECK(test::utils::wait_until([&]() {
+            /*
+             * In consistency test, always do fresh mutation
+             */
+            test_value = test::utils::uniq_id("value");
+            document = {
+                { "testkey", test_value },
+            };
+            {
+                auto [ctx2, _] = collection.upsert(key, document).get();
+                REQUIRE_SUCCESS(ctx2.ec());
+            }
+
+            std::tie(ctx, resp) =
+              cluster
+                .analytics_query(fmt::format(R"(SELECT testkey FROM `Default`.`{}` WHERE testkey = "{}")", dataset_name, test_value),
+                                 couchbase::analytics_options{}.scan_consistency(couchbase::analytics_scan_consistency::request_plus))
+                .get();
+            /* Analytics might give us code 23027, ignore it here
+             *
+             * "errors": [{"code": 23027, "msg": "Bucket default on link Default.Local is not connected"} ],
+             */
+            return ctx.first_error_code() != 23027;
+        }));
+
+        REQUIRE_SUCCESS(ctx.ec());
+        auto rows = resp.rows_as_json();
+        REQUIRE(rows.size() == 1);
+        REQUIRE(rows[0] == document);
+    }
+
+    SECTION("readonly")
+    {
+        auto [ctx, resp] =
+          cluster.analytics_query(fmt::format("DROP DATASET Default.`{}`", dataset_name), couchbase::analytics_options{}.readonly(true))
+            .get();
+
+        REQUIRE(ctx.ec() == couchbase::errc::common::internal_server_failure);
+        REQUIRE(resp.meta_data().status() == couchbase::analytics_status::fatal);
+    }
+
+    {
+        couchbase::core::operations::management::analytics_dataset_drop_request req{};
+        req.dataset_name = dataset_name;
+        test::utils::execute(integration.cluster, req);
+    }
+}
+
+TEST_CASE("integration: public API analytics scope query")
+{
+    test::utils::integration_test_guard integration;
+
+    if (!integration.cluster_version().supports_analytics() || !integration.cluster_version().supports_collections()) {
+        return;
+    }
+
+    auto cluster = couchbase::cluster(integration.cluster);
+    auto bucket = cluster.bucket(integration.ctx.bucket);
+
+    auto scope_name = test::utils::uniq_id("scope");
+    auto collection_name = test::utils::uniq_id("collection");
+
+    {
+        const couchbase::core::operations::management::scope_create_request req{ integration.ctx.bucket, scope_name };
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE_SUCCESS(resp.ctx.ec);
+        auto created = test::utils::wait_until_collection_manifest_propagated(integration.cluster, integration.ctx.bucket, resp.uid);
+        REQUIRE(created);
+    }
+
+    {
+        const couchbase::core::operations::management::collection_create_request req{ integration.ctx.bucket, scope_name, collection_name };
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE_SUCCESS(resp.ctx.ec);
+        auto created = test::utils::wait_until_collection_manifest_propagated(integration.cluster, integration.ctx.bucket, resp.uid);
+        REQUIRE(created);
+    }
+
+    CHECK(test::utils::wait_until(
+      [&]() {
+          auto [ctx, resp] = cluster
+                               .analytics_query(fmt::format(
+                                 "ALTER COLLECTION `{}`.`{}`.`{}` ENABLE ANALYTICS", integration.ctx.bucket, scope_name, collection_name))
+                               .get();
+          return !ctx.ec();
+      },
+      std::chrono::minutes{ 5 }));
+
+    auto scope = bucket.scope(scope_name);
+    auto collection = scope.collection(collection_name);
+
+    auto key = test::utils::uniq_id("key");
+    auto test_value = test::utils::uniq_id("value");
+    const tao::json::value document = {
+        { "testkey", test_value },
+    };
+    {
+        auto [ctx, resp] = collection.upsert(key, document).get();
+        REQUIRE_SUCCESS(ctx.ec());
+    }
+
+    couchbase::analytics_result resp{};
+    couchbase::analytics_error_context ctx{};
+    CHECK(test::utils::wait_until([&]() {
+        std::tie(ctx, resp) =
+          scope.analytics_query(fmt::format(R"(SELECT testkey FROM `{}` WHERE testkey = "{}")", collection_name, test_value)).get();
+        return !ctx.ec() && resp.meta_data().metrics().result_count() == 1;
+    }));
+    REQUIRE_SUCCESS(ctx.ec());
+    REQUIRE(resp.rows_as_json()[0] == document);
+    REQUIRE_FALSE(resp.meta_data().request_id().empty());
+    REQUIRE_FALSE(resp.meta_data().client_context_id().empty());
+    REQUIRE(resp.meta_data().status() == couchbase::analytics_status::success);
+
+    {
+        const couchbase::core::operations::management::scope_drop_request req{ integration.ctx.bucket, scope_name };
+        test::utils::execute(integration.cluster, req);
+    }
+}

package/deps/couchbase-cxx-client/test/test_integration_crud.cxx

@@ -29,6 +29,32 @@ static const tao::json::value basic_doc = {
 };
 static const std::vector<std::byte> basic_doc_json = couchbase::core::utils::json::generate_binary(basic_doc);
 
+TEST_CASE("integration: switching off mutation token", "[integration]")
+{
+    couchbase::core::cluster_options opts{};
+    opts.enable_mutation_tokens = false;
+    test::utils::integration_test_guard integration(opts);
+
+    test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
+    couchbase::core::document_id id{ integration.ctx.bucket, "_default", "_default", test::utils::uniq_id("foo") };
+
+    {
+        couchbase::core::operations::insert_request req{ id, basic_doc_json };
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE_SUCCESS(resp.ctx.ec());
+        REQUIRE(!resp.cas.empty());
+        REQUIRE(resp.token.sequence_number() == 0);
+        REQUIRE(resp.token.partition_uuid() == 0);
+        REQUIRE_FALSE(resp.token.partition_id() == 0);
+        REQUIRE_FALSE(resp.token.bucket_name().empty());
+    }
+    {
+        couchbase::core::operations::get_request req{ id };
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE(resp.value == basic_doc_json);
+    }
+}
+
 TEST_CASE("integration: crud on default collection", "[integration]")
 {
     test::utils::integration_test_guard integration;
@@ -202,6 +228,9 @@ TEST_CASE("integration: pessimistic locking", "[integration]")
     {
         couchbase::core::operations::get_and_lock_request req{ id };
         req.lock_time = lock_time;
+        if (integration.ctx.deployment == test::utils::deployment_type::capella) {
+            req.timeout = std::chrono::seconds{ 2 };
+        }
         auto resp = test::utils::execute(integration.cluster, req);
         REQUIRE(resp.ctx.ec() == couchbase::errc::common::ambiguous_timeout);
         REQUIRE(resp.ctx.retried_because_of(couchbase::retry_reason::key_value_locked));
@@ -784,7 +813,11 @@ TEST_CASE("integration: pessimistic locking with public API", "[integration]")
 
     // it is not allowed to lock the same key twice
     {
-        auto [ctx, resp] = collection.get_and_lock(id, lock_time, {}).get();
+        couchbase::get_and_lock_options options{};
+        if (integration.ctx.deployment == test::utils::deployment_type::capella) {
+            options.timeout(std::chrono::seconds{ 2 });
+        }
+        auto [ctx, resp] = collection.get_and_lock(id, lock_time, options).get();
         REQUIRE(ctx.ec() == couchbase::errc::common::ambiguous_timeout);
         REQUIRE(ctx.retried_because_of(couchbase::retry_reason::key_value_locked));
     }
@@ -868,3 +901,49 @@ TEST_CASE("integration: exists with public API", "[integration]")
         REQUIRE_FALSE(resp.exists());
     }
 }
+
+TEST_CASE("integration: get with expiry with public API", "[integration]")
+{
+    test::utils::integration_test_guard integration;
+    test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
+
+    auto collection = couchbase::cluster(integration.cluster)
+                        .bucket(integration.ctx.bucket)
+                        .scope(couchbase::scope::default_name)
+                        .collection(couchbase::collection::default_name);
+
+    auto id = test::utils::uniq_id("get_expiry");
+
+    auto get_options = couchbase::get_options{}.with_expiry(true);
+
+    SECTION("no expiry set on the document")
+    {
+        {
+            auto [ctx, resp] = collection.insert(id, basic_doc, {}).get();
+            REQUIRE_SUCCESS(ctx.ec());
+        }
+
+        {
+            auto [ctx, resp] = collection.get(id, get_options).get();
+            REQUIRE_SUCCESS(ctx.ec());
+            REQUIRE_FALSE(resp.expiry_time().has_value());
+        }
+    }
+
+    SECTION("some expiry is set on the document")
+    {
+        auto the_expiry = std::chrono::system_clock::from_time_t(1878422400);
+        auto insert_options = couchbase::insert_options{}.expiry(the_expiry);
+        {
+            auto [ctx, resp] = collection.insert(id, basic_doc, insert_options).get();
+            REQUIRE_SUCCESS(ctx.ec());
+        }
+
+        {
+            auto [ctx, resp] = collection.get(id, get_options).get();
+            REQUIRE_SUCCESS(ctx.ec());
+            REQUIRE(resp.expiry_time().has_value());
+            REQUIRE(resp.expiry_time().value() == the_expiry);
+        }
+    }
+}

package/deps/couchbase-cxx-client/test/test_integration_diagnostics.cxx

@@ -326,9 +326,9 @@ TEST_CASE("integration: fetch diagnostics after N1QL query", "[integration]")
         couchbase::core::operations::query_request req{ "SELECT 'hello, couchbase' AS greetings" };
         auto resp = test::utils::execute(integration.cluster, req);
         REQUIRE_SUCCESS(resp.ctx.ec);
-        INFO("rows.size() =" << resp.rows.size())
+        INFO("rows.size() =" << resp.rows.size());
         REQUIRE(resp.rows.size() == 1);
-        INFO("row=" << resp.rows[0])
+        INFO("row=" << resp.rows[0]);
         REQUIRE(resp.rows[0] == R"({"greetings":"hello, couchbase"})");
     }
     {
@@ -385,7 +385,7 @@ TEST_CASE("integration: ping", "[integration]")
         }
 
         REQUIRE(res.id == "my_report_id");
-        INFO(res.sdk)
+        INFO(res.sdk);
         REQUIRE(res.sdk.find("cxx/") == 0);
     }
 }

package/deps/couchbase-cxx-client/test/test_integration_examples.cxx

@@ -0,0 +1,182 @@
+/* -*- 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 "core/operations/management/query_index_build.hxx"
+#include "core/operations/management/query_index_create.hxx"
+#include "core/operations/management/query_index_get_all.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;
+    }
+
+    {
+        couchbase::core::operations::management::query_index_create_request req{};
+        req.index_name = "def_inventory_airline_primary";
+        req.bucket_name = "travel-sample";
+        req.scope_name = "inventory";
+        req.collection_name = "airline";
+        req.is_primary = true;
+        req.ignore_if_exists = true;
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE_FALSE(resp.ctx.ec);
+    }
+
+    {
+        couchbase::core::operations::management::query_index_build_request req{};
+        req.index_names = { "def_inventory_airline_primary" };
+        req.bucket_name = "travel-sample";
+        req.scope_name = "inventory";
+        req.collection_name = "airline";
+        auto resp = test::utils::execute(integration.cluster, req);
+        REQUIRE_FALSE(resp.ctx.ec);
+    }
+
+    CHECK(test::utils::wait_until(
+      [&integration]() {
+          couchbase::core::operations::management::query_index_get_all_request req{};
+          req.bucket_name = "travel-sample";
+          req.scope_name = "inventory";
+          auto resp = test::utils::execute(integration.cluster, req);
+          if (resp.ctx.ec) {
+              return false;
+          }
+          return std::any_of(resp.indexes.begin(), resp.indexes.end(), [](const auto& index) {
+              return index.collection_name == "airline" && index.is_primary && index.state == "online";
+          });
+      },
+      std::chrono::minutes{ 5 }));
+
+    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);
+}