feat(bigtable): add explicit instance MakeDataConnection

Author: scotthart

CHANGELOG.md

@@ -16,6 +16,20 @@ the APIs in these libraries are stable, and are ready for production use.
 
 - [Agent Registry API](/google/cloud/agentregistry/README.md)
 
+### [Bigtable](/google/cloud/bigtable/README.md)
+
+- Explicit instance declaration is now encouraged during client initialization via a new overload of `MakeDataConnection` that takes a `std::vector<InstanceResource>`. Specifying the target instances at client startup enables optimizing connection pooling (pre-warming/priming channels) and telemetry.
+
+  ```cpp
+  #include "google/cloud/bigtable/data_connection.h"
+
+  namespace cbt = ::google::cloud::bigtable;
+
+  auto connection = cbt::MakeDataConnection(
+      {cbt::InstanceResource(google::cloud::Project("my-project"), "my-instance")},
+      google::cloud::Options{});
+  ```
+
 ## v3.6.0 - 2026-06
 
 ### New Libraries

google/cloud/bigtable/data_connection.cc

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/bigtable/data_connection.h"
 #include "google/cloud/bigtable/internal/bigtable_stub_factory.h"
 #include "google/cloud/bigtable/internal/data_connection_impl.h"
@@ -174,6 +175,13 @@ bigtable::RowStream DataConnection::ExecuteQuery(bigtable::ExecuteQueryParams) {
           Status(StatusCode::kUnimplemented, "not implemented")));
 }
 
+std::shared_ptr<DataConnection> MakeDataConnection(
+    std::vector<InstanceResource> instances, Options options) {
+  options.set<experimental::InstanceChannelAffinityOption>(
+      std::move(instances));
+  return MakeDataConnection(std::move(options));
+}
+
 std::shared_ptr<DataConnection> MakeDataConnection(Options options) {
   google::cloud::internal::CheckExpectedOptions<
       AppProfileIdOption, CommonOptionList, GrpcOptionList,

google/cloud/bigtable/data_connection.h

@@ -16,6 +16,7 @@
 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_DATA_CONNECTION_H
 
 #include "google/cloud/bigtable/filters.h"
+#include "google/cloud/bigtable/instance_resource.h"
 #include "google/cloud/bigtable/internal/bigtable_stub.h"
 #include "google/cloud/bigtable/mutation_branch.h"
 #include "google/cloud/bigtable/mutations.h"
@@ -33,6 +34,7 @@
 #include "google/cloud/stream_range.h"
 #include "google/cloud/version.h"
 #include <memory>
+#include <vector>
 
 namespace google {
 namespace cloud {
@@ -168,6 +170,10 @@ class DataConnection {
  * Returns a `DataConnection` object that can be used for interacting with
  * the Cloud Bigtable Data API.
  *
+ * Calling this function with a list of target @p instances automatically
+ * enables dynamic channel pooling for those instances, allowing the connection
+ * pools to scale dynamically based on outstanding RPC load.
+ *
  * The returned connection object should not be used directly; instead it
  * should be given to a `Table` instance, and methods should be invoked on
  * `Table`.
@@ -186,9 +192,27 @@ class DataConnection {
  *     `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and unexpected
  *     options will be logged.
  *
+ * @param instances The target instances to connect to. Specifying target
+ *     instances enables dynamic channel pooling and other connection-level
+ *     optimizations.
+ * @param options (optional) Configure the `DataConnection` created by this
+ *     function.
+ */
+std::shared_ptr<DataConnection> MakeDataConnection(
+    std::vector<InstanceResource> instances, Options options = {});
+
+/**
+ * Returns a `DataConnection` object that can be used for interacting with
+ * the Cloud Bigtable Data API.
+ *
+ * @deprecated Use the MakeDataConnection overload that accepts a vector of
+ *     instances.
+ *
  * @param options (optional) Configure the `DataConnection` created by this
  *     function.
  */
+GOOGLE_CLOUD_CPP_DEPRECATED(
+    "Use the MakeDataConnection overload that accepts a vector of instances.")
 std::shared_ptr<DataConnection> MakeDataConnection(Options options = {});
 
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END

google/cloud/bigtable/data_connection_test.cc

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/bigtable/data_connection.h"
 #include "google/cloud/bigtable/internal/bigtable_stub_factory.h"
 #include "google/cloud/bigtable/options.h"
@@ -100,6 +101,22 @@ TEST(MakeDataConnection, TracingDisabled) {
   EXPECT_THAT(span_catcher->GetSpans(), IsEmpty());
 }
 
+TEST(MakeDataConnection, WithInstances) {
+  InstanceResource instance_a{Project("my-project"), "instance-a"};
+  InstanceResource instance_b{Project("my-project"), "instance-b"};
+  auto conn = MakeDataConnection(
+      {instance_a, instance_b},
+      TestOptions().set<AppProfileIdOption>("user-supplied"));
+  auto options = conn->options();
+  EXPECT_TRUE(options.has<DataBackoffPolicyOption>())
+      << "Options are not defaulted in MakeDataConnection()";
+  EXPECT_EQ(options.get<AppProfileIdOption>(), "user-supplied")
+      << "User supplied Options are overridden in MakeDataConnection()";
+  ASSERT_TRUE(options.has<experimental::InstanceChannelAffinityOption>());
+  EXPECT_THAT(options.get<experimental::InstanceChannelAffinityOption>().size(),
+              Eq(2));
+}
+
 }  // namespace
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace bigtable

google/cloud/bigtable/internal/stub_manager.cc

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 #include "google/cloud/bigtable/internal/stub_manager.h"
+#include "google/cloud/log.h"
 #include <utility>
 
 namespace google {
@@ -39,6 +40,8 @@ std::shared_ptr<BigtableStub> StubManager::GetStub(
       iter != affinity_stubs_.end()) {
     return iter->second;
   }
+  GCP_LOG(INFO) << "Dynamic connection resolution adding new channel pool "
+                << "for instance: " << instance_name;
   auto inserted = affinity_stubs_.emplace(
       std::string{instance_name},
       stub_creation_fn_(instance_name, Priming::kNoPriming));

google/cloud/bigtable/internal/stub_manager_test.cc

@@ -16,6 +16,7 @@
 #include "google/cloud/bigtable/instance_resource.h"
 #include "google/cloud/bigtable/table_resource.h"
 #include "google/cloud/bigtable/testing/mock_bigtable_stub.h"
+#include "google/cloud/testing_util/scoped_log.h"
 #include "google/cloud/testing_util/status_matchers.h"
 #include <gmock/gmock.h>
 
@@ -27,7 +28,9 @@ namespace {
 
 using ::google::cloud::bigtable::testing::MockBigtableStub;
 using ::google::cloud::testing_util::IsOk;
+using ::testing::Contains;
 using ::testing::Eq;
+using ::testing::HasSubstr;
 using ::testing::MockFunction;
 using ::testing::StartsWith;
 
@@ -87,6 +90,7 @@ TEST(StubManagerTest, AffinityToExistingInstance) {
 }
 
 TEST(StubManagerTest, AffinityToMissingInstance) {
+  testing_util::ScopedLog log;
   bigtable::InstanceResource instance_a(Project("my-project"), "a");
   bigtable::TableResource table_a(instance_a, "my-table");
   auto mock_stub_a = std::make_shared<MockBigtableStub>();
@@ -119,6 +123,9 @@ TEST(StubManagerTest, AffinityToMissingInstance) {
   request.set_table_name(expected_table_name);
   auto result = stub->MutateRow(context, {}, request);
   EXPECT_THAT(result, IsOk());
+  EXPECT_THAT(log.ExtractLines(),
+              Contains(HasSubstr(
+                  "Dynamic connection resolution adding new channel pool")));
 }
 
 }  // namespace