feat(bigtable): add explicit instance MakeDataConnection

Author: scotthart

CHANGELOG.md

@@ -9,6 +9,20 @@ for details on updating existing applications using v1.x.y or v2.x.y.
 
 ## v3.7.0 - TBD
 
+### [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`.
@@ -189,6 +195,21 @@ class DataConnection {
  * @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