From 56dd1b21a6fce0bb2160d1b712b072b5dcefd1b1 Mon Sep 17 00:00:00 2001
From: Lawrence Qiu <lawrenceqiu@google.com>
Date: Fri, 24 Apr 2026 11:19:21 -0400
Subject: [PATCH 1/4] fix(datastore): Update initial ChannelPool configs
 according to Datastore best practice guide

---
 .../cloud/datastore/DatastoreOptions.java     | 19 ++++++++++++++-----
 .../cloud/datastore/DatastoreOptionsTest.java | 13 ++++++++-----
 2 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
index 70d1c568ec95..2aa84981fb87 100644
--- a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
@@ -53,12 +53,19 @@ public class DatastoreOptions extends ServiceOptions<Datastore, DatastoreOptions
   private static final String DEFAULT_DATABASE_ID = "";
   public static final String PROJECT_ID_ENV_VAR = "DATASTORE_PROJECT_ID";
   public static final String LOCAL_HOST_ENV_VAR = "DATASTORE_EMULATOR_HOST";
+
+  // Default to a slightly larger channel count to handle a larger initial QPS (up to ~500 QPS as
+  // each channel can handle 100 max streams). This default remains a bit conservative and will
+  // rely on the ChannelPool to resize according to the client's average load.
   public static final int INIT_CHANNEL_COUNT = 5;
+  // Default to be larger than Gax's default (2) to better scale with spikes in requests
   static final int CHANNEL_POOL_DEFAULT_RESIZE_DELTA = 5;
-  // Configure this default to be 100 to match the typical default `MAX_CONCURRENT_STREAMS`.
-  // Larger values *may* experience possible client-side queueing as excess streams cannot be
-  // multiplexed onto a full Http2 connection.
-  static final int CHANNEL_POOL_MAX_RPCS_PER_CHANNEL = 100;
+
+  // Configure the min and max RPC/Channel default in accordance to Datastore configuration guide:
+  // https://docs.cloud.google.com/datastore/docs/java-client-grpc#connection_pool_configuration
+  static final int CHANNEL_POOL_MIN_RPCS_PER_CHANNEL = 10;
+  static final int CHANNEL_POOL_MAX_RPCS_PER_CHANNEL = 50;
+
   public static final int MIN_CHANNEL_COUNT = 1;
 
   // This is a default max channel constant value set to handle the default initial channel
@@ -246,11 +253,13 @@ private DatastoreOptions(Builder builder) {
         // Datastore sets the initial channel pool count to be 5 channels to allow better handle
         // large loads of requests and the resize delta to be 5 to scale quicker. In cases of low
         // load, the channel count will scale down as needed and memory will be freed. The default
-        // configuration is set to try and handle ~500 QPS and will scale up and down as needed.
+        // configuration is set to try and handle an average of ~250 QPS and will scale up and down
+        // as needed.
         ChannelPoolSettings datastoreChannelPoolSettings =
             ChannelPoolSettings.builder()
                 .setInitialChannelCount(INIT_CHANNEL_COUNT)
                 .setMinChannelCount(MIN_CHANNEL_COUNT)
+                .setMinRpcsPerChannel(CHANNEL_POOL_MIN_RPCS_PER_CHANNEL)
                 .setMaxRpcsPerChannel(CHANNEL_POOL_MAX_RPCS_PER_CHANNEL)
                 .setMaxResizeDelta(CHANNEL_POOL_DEFAULT_RESIZE_DELTA)
                 .build();
diff --git a/java-datastore/google-cloud-datastore/src/test/java/com/google/cloud/datastore/DatastoreOptionsTest.java b/java-datastore/google-cloud-datastore/src/test/java/com/google/cloud/datastore/DatastoreOptionsTest.java
index 79e9ab965aa1..c5e5186200ac 100644
--- a/java-datastore/google-cloud-datastore/src/test/java/com/google/cloud/datastore/DatastoreOptionsTest.java
+++ b/java-datastore/google-cloud-datastore/src/test/java/com/google/cloud/datastore/DatastoreOptionsTest.java
@@ -184,12 +184,15 @@ public void testGrpcDefaultChannelConfigurations() {
     ChannelPoolSettings channelPoolSettings =
         ((InstantiatingGrpcChannelProvider) datastoreOptions.getTransportChannelProvider())
             .getChannelPoolSettings();
-    assertEquals(channelPoolSettings.getInitialChannelCount(), DatastoreOptions.INIT_CHANNEL_COUNT);
-    assertEquals(channelPoolSettings.getMinChannelCount(), DatastoreOptions.MIN_CHANNEL_COUNT);
-    assertEquals(channelPoolSettings.getMaxChannelCount(), DEFAULT_MAX_CHANNEL_COUNT);
+    assertEquals(DatastoreOptions.INIT_CHANNEL_COUNT, channelPoolSettings.getInitialChannelCount());
+    assertEquals(DatastoreOptions.MIN_CHANNEL_COUNT, channelPoolSettings.getMinChannelCount());
+    assertEquals(DEFAULT_MAX_CHANNEL_COUNT, channelPoolSettings.getMaxChannelCount());
     assertEquals(
-        channelPoolSettings.getMaxRpcsPerChannel(),
-        DatastoreOptions.CHANNEL_POOL_MAX_RPCS_PER_CHANNEL);
+        DatastoreOptions.CHANNEL_POOL_MIN_RPCS_PER_CHANNEL,
+        channelPoolSettings.getMinRpcsPerChannel());
+    assertEquals(
+        DatastoreOptions.CHANNEL_POOL_MAX_RPCS_PER_CHANNEL,
+        channelPoolSettings.getMaxRpcsPerChannel());
   }
 
   @Test

From e6b0c09e3f24dc750502ce5b8752f3c893f55e6e Mon Sep 17 00:00:00 2001
From: Lawrence Qiu <lawrenceqiu@google.com>
Date: Fri, 24 Apr 2026 11:36:51 -0400
Subject: [PATCH 2/4] chore: Address confusing code comment

---
 .../com/google/cloud/datastore/DatastoreOptions.java   | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
index 2aa84981fb87..9ecf53fc8a41 100644
--- a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
@@ -54,9 +54,13 @@ public class DatastoreOptions extends ServiceOptions<Datastore, DatastoreOptions
   public static final String PROJECT_ID_ENV_VAR = "DATASTORE_PROJECT_ID";
   public static final String LOCAL_HOST_ENV_VAR = "DATASTORE_EMULATOR_HOST";
 
-  // Default to a slightly larger channel count to handle a larger initial QPS (up to ~500 QPS as
-  // each channel can handle 100 max streams). This default remains a bit conservative and will
-  // rely on the ChannelPool to resize according to the client's average load.
+  // Default to a slightly larger channel count to handle a larger initial QPS. The initial
+  // configuration
+  // should be able to handle a max of ~500 QPS as each gRPC channel can handle 100 max streams
+  // (limited
+  // by Google Middleware). This default relies on the ChannelPool to resize according to the
+  // client's
+  // average load.
   public static final int INIT_CHANNEL_COUNT = 5;
   // Default to be larger than Gax's default (2) to better scale with spikes in requests
   static final int CHANNEL_POOL_DEFAULT_RESIZE_DELTA = 5;

From f64c7b1f58fad28a1c1ff2c2d0d0dc5ea9f1c39c Mon Sep 17 00:00:00 2001
From: Lawrence Qiu <lawrenceqiu@google.com>
Date: Fri, 24 Apr 2026 11:39:18 -0400
Subject: [PATCH 3/4] chore: Fix lint

---
 .../com/google/cloud/datastore/DatastoreOptions.java     | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
index 9ecf53fc8a41..5dcc7da8f006 100644
--- a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
@@ -55,12 +55,9 @@ public class DatastoreOptions extends ServiceOptions<Datastore, DatastoreOptions
   public static final String LOCAL_HOST_ENV_VAR = "DATASTORE_EMULATOR_HOST";
 
   // Default to a slightly larger channel count to handle a larger initial QPS. The initial
-  // configuration
-  // should be able to handle a max of ~500 QPS as each gRPC channel can handle 100 max streams
-  // (limited
-  // by Google Middleware). This default relies on the ChannelPool to resize according to the
-  // client's
-  // average load.
+  // configuration should be able to handle a max of ~500 QPS as each gRPC channel can handle
+  // 100 max streams (limited by Google Middleware). This default relies on the ChannelPool
+  // to resize according to the client's average load.
   public static final int INIT_CHANNEL_COUNT = 5;
   // Default to be larger than Gax's default (2) to better scale with spikes in requests
   static final int CHANNEL_POOL_DEFAULT_RESIZE_DELTA = 5;

From adebddc5029d0de3b86f4dbe3649bbb3b86984a1 Mon Sep 17 00:00:00 2001
From: Lawrence Qiu <lawrenceqiu@google.com>
Date: Fri, 24 Apr 2026 11:44:19 -0400
Subject: [PATCH 4/4] chore: Clarify code comment to differentiate theoretical
 max and expected max

---
 .../java/com/google/cloud/datastore/DatastoreOptions.java    | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
index 5dcc7da8f006..c1453b22bfde 100644
--- a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreOptions.java
@@ -55,8 +55,9 @@ public class DatastoreOptions extends ServiceOptions<Datastore, DatastoreOptions
   public static final String LOCAL_HOST_ENV_VAR = "DATASTORE_EMULATOR_HOST";
 
   // Default to a slightly larger channel count to handle a larger initial QPS. The initial
-  // configuration should be able to handle a max of ~500 QPS as each gRPC channel can handle
-  // 100 max streams (limited by Google Middleware). This default relies on the ChannelPool
+  // configuration should be able to handle a max of ~500 concurrent streams as each gRPC
+  // channel can handle a max of 100 streams (limited by Google Middleware). The initial
+  // configuration aims to have a max of ~250 concurrent streams and will rely on the ChannelPool
   // to resize according to the client's average load.
   public static final int INIT_CHANNEL_COUNT = 5;
   // Default to be larger than Gax's default (2) to better scale with spikes in requests