feat(bigtable): add explicit instance MakeDataConnection (#16191)

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/benchmarks/benchmark.cc

@@ -130,10 +130,13 @@ void Benchmark::DeleteTable() {
 Table Benchmark::MakeTable(Options connection_opts) const {
   auto connection_options = MergeOptions(std::move(connection_opts), opts_);
   auto table_opts = Options{}.set<AppProfileIdOption>(options_.app_profile_id);
-  return Table(MakeDataConnection(std::move(connection_options)),
-               TableResource(options_.project_id, options_.instance_id,
-                             options_.table_id),
-               std::move(table_opts));
+  return Table(
+      MakeDataConnection({InstanceResource(Project(options_.project_id),
+                                           options_.instance_id)},
+                         std::move(connection_options)),
+      TableResource(options_.project_id, options_.instance_id,
+                    options_.table_id),
+      std::move(table_opts));
 }
 
 google::cloud::StatusOr<BenchmarkResult> Benchmark::PopulateTable() {

google/cloud/bigtable/benchmarks/embedded_server_test.cc

@@ -76,7 +76,9 @@ TEST(EmbeddedServer, TableApply) {
           .set<GrpcCredentialOption>(grpc::InsecureChannelCredentials())
           .set<EndpointOption>(server->address());
 
-  Table table(MakeDataConnection(options),
+  Table table(MakeDataConnection(
+                  {InstanceResource(Project("fake-project"), "fake-instance")},
+                  std::move(options)),
               TableResource("fake-project", "fake-instance", "fake-table"));
 
   SingleRowMutation mutation("row1",
@@ -101,7 +103,9 @@ TEST(EmbeddedServer, TableBulkApply) {
           .set<GrpcCredentialOption>(grpc::InsecureChannelCredentials())
           .set<EndpointOption>(server->address());
 
-  Table table(MakeDataConnection(options),
+  Table table(MakeDataConnection(
+                  {InstanceResource(Project("fake-project"), "fake-instance")},
+                  std::move(options)),
               TableResource("fake-project", "fake-instance", "fake-table"));
 
   BulkMutation bulk;
@@ -128,7 +132,9 @@ TEST(EmbeddedServer, ReadRows1) {
           .set<GrpcCredentialOption>(grpc::InsecureChannelCredentials())
           .set<EndpointOption>(server->address());
 
-  Table table(MakeDataConnection(options),
+  Table table(MakeDataConnection(
+                  {InstanceResource(Project("fake-project"), "fake-instance")},
+                  std::move(options)),
               TableResource("fake-project", "fake-instance", "fake-table"));
 
   EXPECT_EQ(0, server->read_rows_count());
@@ -150,7 +156,9 @@ TEST(EmbeddedServer, ReadRows100) {
           .set<GrpcCredentialOption>(grpc::InsecureChannelCredentials())
           .set<EndpointOption>(server->address());
 
-  Table table(MakeDataConnection(options),
+  Table table(MakeDataConnection(
+                  {InstanceResource(Project("fake-project"), "fake-instance")},
+                  std::move(options)),
               TableResource("fake-project", "fake-instance", "fake-table"));
 
   EXPECT_EQ(0, server->read_rows_count());

google/cloud/bigtable/benchmarks/mutation_batcher_throughput_benchmark.cc

@@ -201,6 +201,8 @@ int main(int argc, char* argv[]) {
 
   auto table = cbt::Table(
       cbt::MakeDataConnection(
+          {cbt::InstanceResource(google::cloud::Project(options->project_id),
+                                 options->instance_id)},
           Options{}.set<google::cloud::GrpcBackgroundThreadPoolSizeOption>(
               options->max_batches)),
       cbt::TableResource(options->project_id, options->instance_id, *table_id));

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/examples/bigtable_examples_common.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/examples/bigtable_examples_common.h"
 #include "google/cloud/internal/getenv.h"
 #include "absl/strings/str_join.h"
@@ -53,7 +54,9 @@ Commands::value_type MakeCommandEntry(std::string const& name,
       throw Usage{std::move(os).str()};
     }
     google::cloud::bigtable::Table table(
-        google::cloud::bigtable::MakeDataConnection(),
+        google::cloud::bigtable::MakeDataConnection(
+            {google::cloud::bigtable::InstanceResource(
+                google::cloud::Project(argv[0]), argv[1])}),
         google::cloud::bigtable::TableResource(argv[0], argv[1], argv[2]));
     argv.erase(argv.begin(), argv.begin() + 3);
     function(table, argv);
@@ -118,7 +121,9 @@ Commands::value_type MakeCommandEntry(std::string const& name,
       throw Usage{std::move(os).str()};
     }
     google::cloud::bigtable::Table table(
-        google::cloud::bigtable::MakeDataConnection(),
+        google::cloud::bigtable::MakeDataConnection(
+            {google::cloud::bigtable::InstanceResource(
+                google::cloud::Project(argv[0]), argv[1])}),
         google::cloud::bigtable::TableResource(argv[0], argv[1], argv[2]));
     google::cloud::CompletionQueue cq;
     std::thread t([&cq] { cq.Run(); });

google/cloud/bigtable/examples/bigtable_hello_app_profile.cc

@@ -43,7 +43,8 @@ void HelloWorldAppProfile(std::vector<std::string> const& argv) {
   std::string const& profile_id = argv[3];
 
   // Create an object to access the Cloud Bigtable Data API.
-  auto connection = cbt::MakeDataConnection();
+  auto connection = cbt::MakeDataConnection(
+      {cbt::InstanceResource(google::cloud::Project(project_id), instance_id)});
 
   // Use the default profile to write some data.
   cbt::Table write(connection,

google/cloud/bigtable/examples/bigtable_hello_world.cc

@@ -52,7 +52,8 @@ void BigtableHelloWorld(std::vector<std::string> const& argv) {
 
   //! [connect data]
   // Create an object to access the Cloud Bigtable Data API.
-  cbt::Table table(cbt::MakeDataConnection(),
+  cbt::Table table(cbt::MakeDataConnection({cbt::InstanceResource(
+                       google::cloud::Project(project_id), instance_id)}),
                    cbt::TableResource(project_id, instance_id, table_id));
   //! [connect data]
   //! [connect admin] [END bigtable_hw_connect]