feat(spanner): add cache updates API (#8307)

Co-authored-by: alkatrivedi <58396306+alkatrivedi@users.noreply.github.com>

Author: pearigee

handwritten/spanner/.OwlBot.yaml

@@ -1,30 +1,19 @@
-# Copyright 2021 Google LLC
+# Copyright 2025 Google LLC
 #
 # 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
+#      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.
 
-
-deep-remove-regex:
-  - /owl-bot-staging
-
 deep-copy-regex:
-  - source: /google/spanner/(v.*)/.*-nodejs
-    dest: /owl-bot-staging/spanner/$1
-  - source: /google/spanner/(admin/database/v.*)/.*-nodejs
-    dest: /owl-bot-staging/spanner/$1
-  - source: /google/spanner/(admin/instance/v.*)/.*-nodejs
-    dest: /owl-bot-staging/spanner/$1
-  - source: /google/spanner/(executor/v.*)/.*-nodejs
-    dest: /owl-bot-staging/spanner/$1
-
-begin-after-commit-hash: 46f25fb1121747b994ff5818963fda84b5e6bfd3
+    - source: /google/spanner/executor/google-spanner-executor-nodejs
+      dest: /owl-bot-staging/google-spanner-executor
 
+api-name: executor

handwritten/spanner/protos/google/spanner/v1/commit_response.proto

@@ -16,7 +16,9 @@ syntax = "proto3";
 
 package google.spanner.v1;
 
+import "google/api/field_behavior.proto";
 import "google/protobuf/timestamp.proto";
+import "google/spanner/v1/location.proto";
 import "google/spanner/v1/transaction.proto";
 
 option csharp_namespace = "Google.Cloud.Spanner.V1";
@@ -61,4 +63,18 @@ message CommitResponse {
   // timestamp at which all reads in the transaction ran. This timestamp is
   // never returned.
   google.protobuf.Timestamp snapshot_timestamp = 5;
+
+  // Optional. A cache update expresses a set of changes the client should
+  // incorporate into its location cache. The client should discard the changes
+  // if they are older than the data it already has. This data can be obtained
+  // in response to requests that included a `RoutingHint` field, but may also
+  // be obtained by explicit location-fetching RPCs which may be added in the
+  // future.
+  CacheUpdate cache_update = 6 [(google.api.field_behavior) = OPTIONAL];
+
+  // The isolation level used for the read-write transaction.
+  TransactionOptions.IsolationLevel isolation_level = 7;
+
+  // The read lock mode used for the read-write transaction.
+  TransactionOptions.ReadWrite.ReadLockMode read_lock_mode = 8;
 }

handwritten/spanner/protos/google/spanner/v1/spanner.proto

@@ -331,6 +331,23 @@ service Spanner {
     };
     option (google.api.method_signature) = "session,mutation_groups";
   }
+
+  // Retrieves a cache update for a given database.
+  //
+  // This RPC can be used to warm up the client cache by fetching key recipes
+  // and server information for a given database. It is recommended to call
+  // this RPC at the beginning of the client's lifecycle, prior to any other
+  // data plane operations.
+  //
+  // The cache update is returned as a stream because the response can be too
+  // large to fit into a single `CacheUpdate` message.
+  rpc FetchCacheUpdate(FetchCacheUpdateRequest) returns (stream CacheUpdate) {
+    option (google.api.http) = {
+      post: "/v1/{database=projects/*/instances/*/databases/*}:cacheUpdate"
+      body: "*"
+    };
+    option (google.api.method_signature) = "database";
+  }
 }
 
 // The request for [CreateSession][google.spanner.v1.Spanner.CreateSession].
@@ -827,7 +844,7 @@ message ExecuteSqlRequest {
   // be assumed until a subsequent `Commit` call completes successfully.
   bool last_statement = 17 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. If present, it makes the Spanner requests location-aware.
+  // Optional. Makes the Spanner requests location-aware if present.
   //
   // It gives the server hints that can be used to route the request
   // to an appropriate server, potentially significantly decreasing latency and
@@ -1268,7 +1285,7 @@ message ReadRequest {
   // transactions.
   LockHint lock_hint = 17 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. If present, it makes the Spanner requests location-aware.
+  // Optional. Makes the Spanner requests location-aware if present.
   //
   // It gives the server hints that can be used to route the request
   // to an appropriate server, potentially significantly decreasing latency and
@@ -1301,6 +1318,14 @@ message BeginTransactionRequest {
   // randomly select one of the mutations from the mutation set and send it as a
   // part of this request.
   Mutation mutation_key = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Makes the Spanner requests location-aware if present.
+  //
+  // It gives the server hints that can be used to route the request
+  // to an appropriate server, potentially significantly decreasing latency and
+  // improving throughput. To achieve improved performance, most fields must be
+  // filled in with accurate values.
+  RoutingHint routing_hint = 5 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for [Commit][google.spanner.v1.Spanner.Commit].
@@ -1355,6 +1380,14 @@ message CommitRequest {
   // results in a `FailedPrecondition` error.
   MultiplexedSessionPrecommitToken precommit_token = 9
       [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Makes the Spanner requests location-aware if present.
+  //
+  // It gives the server hints that can be used to route the request
+  // to an appropriate server, potentially significantly decreasing latency and
+  // improving throughput. To achieve improved performance, most fields must be
+  // filled in with accurate values.
+  RoutingHint routing_hint = 10 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for [Rollback][google.spanner.v1.Spanner.Rollback].
@@ -1417,3 +1450,23 @@ message BatchWriteResponse {
   // condition not being satisfied after evaluation.
   google.protobuf.Timestamp commit_timestamp = 3;
 }
+
+// The request for
+// [FetchCacheUpdate][google.spanner.v1.Spanner.FetchCacheUpdate].
+message FetchCacheUpdateRequest {
+  // Required. The database for which to retrieve the cache update.
+  string database = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "spanner.googleapis.com/Database"
+    }
+  ];
+
+  // Optional. The maximum number of key recipes to return in the response.
+  // If not set, a default limit of 100 will be used.
+  int32 max_recipe_count = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The maximum number of ranges to return in the response.
+  // If not set, a default limit of 10000 will be used.
+  int32 max_range_count = 3 [(google.api.field_behavior) = OPTIONAL];
+}

handwritten/spanner/protos/google/spanner/v1/transaction.proto

@@ -19,6 +19,7 @@ package google.spanner.v1;
 import "google/api/field_behavior.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/timestamp.proto";
+import "google/spanner/v1/location.proto";
 
 option csharp_namespace = "Google.Cloud.Spanner.V1";
 option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
@@ -39,35 +40,46 @@ message TransactionOptions {
       // Default value.
       //
       // * If isolation level is
+      //   [SERIALIZABLE][google.spanner.v1.TransactionOptions.IsolationLevel.SERIALIZABLE],
+      //   locking semantics default to `PESSIMISTIC`.
+      // * If isolation level is
       //   [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ],
-      //   then it is an error to specify `read_lock_mode`. Locking semantics
-      //   default to `OPTIMISTIC`. No validation checks are done for reads,
-      //   except to validate that the data that was served at the snapshot time
-      //   is unchanged at commit time in the following cases:
-      //     1. reads done as part of queries that use `SELECT FOR UPDATE`
-      //     2. reads done as part of statements with a `LOCK_SCANNED_RANGES`
-      //        hint
-      //     3. reads done as part of DML statements
-      // * At all other isolation levels, if `read_lock_mode` is the default
-      //   value, then pessimistic read locks are used.
+      //   locking semantics default to `OPTIMISTIC`.
+      // * See
+      //   [Concurrency
+      //   control](https://cloud.google.com/spanner/docs/concurrency-control)
+      //   for more details.
       READ_LOCK_MODE_UNSPECIFIED = 0;
 
       // Pessimistic lock mode.
       //
-      // Read locks are acquired immediately on read.
-      // Semantics described only applies to
+      // Lock acquisition behavior depends on the isolation level in use. In
       // [SERIALIZABLE][google.spanner.v1.TransactionOptions.IsolationLevel.SERIALIZABLE]
-      // isolation.
+      // isolation, reads and writes acquire necessary locks during transaction
+      // statement execution. In
+      // [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ]
+      // isolation, reads that explicitly request to be locked and writes
+      // acquire locks.
+      // See
+      // [Concurrency
+      // control](https://cloud.google.com/spanner/docs/concurrency-control) for
+      // details on the types of locks acquired at each transaction step.
       PESSIMISTIC = 1;
 
       // Optimistic lock mode.
       //
-      // Locks for reads within the transaction are not acquired on read.
-      // Instead the locks are acquired on a commit to validate that
-      // read/queried data has not changed since the transaction started.
-      // Semantics described only applies to
+      // Lock acquisition behavior depends on the isolation level in use. In
+      // both
       // [SERIALIZABLE][google.spanner.v1.TransactionOptions.IsolationLevel.SERIALIZABLE]
-      // isolation.
+      // and
+      // [REPEATABLE_READ][google.spanner.v1.TransactionOptions.IsolationLevel.REPEATABLE_READ]
+      // isolation, reads and writes do not acquire locks during transaction
+      // statement execution.
+      // See
+      // [Concurrency
+      // control](https://cloud.google.com/spanner/docs/concurrency-control) for
+      // details on how the guarantees of each isolation level are provided at
+      // commit time.
       OPTIMISTIC = 2;
     }
 
@@ -264,6 +276,14 @@ message Transaction {
   // attempt should be passed to the [Commit][google.spanner.v1.Spanner.Commit]
   // request for this transaction.
   MultiplexedSessionPrecommitToken precommit_token = 3;
+
+  // Optional. A cache update expresses a set of changes the client should
+  // incorporate into its location cache. The client should discard the changes
+  // if they are older than the data it already has. This data can be obtained
+  // in response to requests that included a `RoutingHint` field, but may also
+  // be obtained by explicit location-fetching RPCs which may be added in the
+  // future.
+  CacheUpdate cache_update = 5 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // This message is used to select the transaction in which a