feat(spanner): add support for lock_hint enum (#15249)

* feat(spanner): add support for lock_hint enum

Author: mpeddada1

google/cloud/spanner/CMakeLists.txt

@@ -176,6 +176,7 @@ add_library(
     json.h
     keys.cc
     keys.h
+    lock_hint.h
     mutations.cc
     mutations.h
     numeric.cc

google/cloud/spanner/client.cc

@@ -53,44 +53,51 @@ RowStream Client::Read(std::string table, KeySet keys,
                        std::vector<std::string> columns, Options opts) {
   opts = internal::MergeOptions(std::move(opts), opts_);
   auto directed_read_option = ExtractOpt<DirectedReadOption>(opts);
+  auto lock_hint = ExtractOpt<LockHintOption>(opts);
   internal::OptionsSpan span(std::move(opts));
   return conn_->Read({spanner_internal::MakeSingleUseTransaction(
                           Transaction::ReadOnlyOptions()),
                       std::move(table), std::move(keys), std::move(columns),
                       ToReadOptions(internal::CurrentOptions()), absl::nullopt,
-                      false, std::move(directed_read_option)});
+                      false, std::move(directed_read_option),
+                      std::move(lock_hint)});
 }
 
 RowStream Client::Read(Transaction::SingleUseOptions transaction_options,
                        std::string table, KeySet keys,
                        std::vector<std::string> columns, Options opts) {
   opts = internal::MergeOptions(std::move(opts), opts_);
   auto directed_read_option = ExtractOpt<DirectedReadOption>(opts);
+  auto lock_hint = ExtractOpt<LockHintOption>(opts);
   internal::OptionsSpan span(std::move(opts));
   return conn_->Read({spanner_internal::MakeSingleUseTransaction(
                           std::move(transaction_options)),
                       std::move(table), std::move(keys), std::move(columns),
                       ToReadOptions(internal::CurrentOptions()), absl::nullopt,
-                      false, std::move(directed_read_option)});
+                      false, std::move(directed_read_option),
+                      std::move(lock_hint)});
 }
 
 RowStream Client::Read(Transaction transaction, std::string table, KeySet keys,
                        std::vector<std::string> columns, Options opts) {
   opts = internal::MergeOptions(std::move(opts), opts_);
   auto directed_read_option = ExtractOpt<DirectedReadOption>(opts);
+  auto lock_hint = ExtractOpt<LockHintOption>(opts);
   internal::OptionsSpan span(std::move(opts));
   return conn_->Read({std::move(transaction), std::move(table), std::move(keys),
                       std::move(columns),
                       ToReadOptions(internal::CurrentOptions()), absl::nullopt,
-                      false, std::move(directed_read_option)});
+                      false, std::move(directed_read_option),
+                      std::move(lock_hint)});
 }
 
 RowStream Client::Read(ReadPartition const& read_partition, Options opts) {
   opts = internal::MergeOptions(std::move(opts), opts_);
   auto directed_read_option = ExtractOpt<DirectedReadOption>(opts);
+  auto lock_hint = ExtractOpt<LockHintOption>(opts);
   internal::OptionsSpan span(std::move(opts));
   return conn_->Read(spanner_internal::MakeReadParams(
-      read_partition, std::move(directed_read_option)));
+      read_partition, std::move(directed_read_option), std::move(lock_hint)));
 }
 
 StatusOr<std::vector<ReadPartition>> Client::PartitionRead(
@@ -100,7 +107,8 @@ StatusOr<std::vector<ReadPartition>> Client::PartitionRead(
   return conn_->PartitionRead(
       {{std::move(transaction), std::move(table), std::move(keys),
         std::move(columns), ToReadOptions(internal::CurrentOptions()),
-        absl::nullopt, false, DirectedReadOption::Type{}},
+        absl::nullopt, false, DirectedReadOption::Type{},
+        LockHint::kLockHintUnspecified},
        ToPartitionOptions(internal::CurrentOptions())});
 }
 

google/cloud/spanner/client_test.cc

@@ -138,6 +138,58 @@ TEST(ClientTest, ReadSuccess) {
                                   IsOkAndHolds(RowType("Ann", 42))));
 }
 
+TEST(ClientTest, ReadWithLockHint) {
+  auto conn = std::make_shared<MockConnection>();
+  Client client(conn);
+
+  auto constexpr kText = R"pb(
+    row_type: {
+      fields: {
+        name: "Name",
+        type: { code: INT64 }
+      }
+      fields: {
+        name: "Id",
+        type: { code: INT64 }
+      }
+    }
+  )pb";
+  google::spanner::v1::ResultSetMetadata metadata;
+  ASSERT_TRUE(TextFormat::ParseFromString(kText, &metadata));
+
+  EXPECT_CALL(*conn, Read)
+      .WillOnce([&metadata](Connection::ReadParams const& params) {
+        EXPECT_THAT(
+            params.directed_read_option,
+            VariantWith<IncludeReplicas>(AllOf(
+                Property(&IncludeReplicas::replica_selections,
+                         ElementsAre(ReplicaSelection(ReplicaType::kReadOnly))),
+                Property(&IncludeReplicas::auto_failover_disabled, true))));
+        EXPECT_THAT(params.lock_hint, Eq(LockHint::kLockHintShared));
+        auto source = std::make_unique<MockResultSetSource>();
+        EXPECT_CALL(*source, Metadata()).WillRepeatedly(Return(metadata));
+        EXPECT_CALL(*source, NextRow())
+            .WillOnce(Return(spanner_mocks::MakeRow("Steve", 12)))
+            .WillOnce(Return(spanner_mocks::MakeRow("Ann", 42)))
+            .WillOnce(Return(Row()));
+        return RowStream(std::move(source));
+      });
+
+  KeySet keys = KeySet::All();
+  auto rows = client.Read("table", std::move(keys), {"column1", "column2"},
+                          Options{}
+                              .set<DirectedReadOption>(IncludeReplicas(
+                                  {ReplicaSelection(ReplicaType::kReadOnly)},
+                                  /*auto_failover_disabled=*/true))
+                              .set<LockHintOption>(LockHint::kLockHintShared));
+
+  using RowType = std::tuple<std::string, std::int64_t>;
+  auto stream = StreamOf<RowType>(rows);
+  auto actual = std::vector<StatusOr<RowType>>{stream.begin(), stream.end()};
+  EXPECT_THAT(actual, ElementsAre(IsOkAndHolds(RowType("Steve", 12)),
+                                  IsOkAndHolds(RowType("Ann", 42))));
+}
+
 TEST(ClientTest, ReadFailure) {
   auto conn = std::make_shared<MockConnection>();
   Client client(conn);
@@ -404,7 +456,8 @@ TEST(ClientTest, CommitMutatorSuccess) {
 
   auto conn = std::make_shared<MockConnection>();
   Transaction txn = MakeReadWriteTransaction();  // placeholder
-  Connection::ReadParams actual_read_params{txn, {}, {}, {}, {}, {}, {}, {}};
+  Connection::ReadParams actual_read_params{txn, {}, {}, {}, {},
+                                            {},  {}, {}, {}};
   Connection::CommitParams actual_commit_params{txn, {}, {}};
 
   auto source = std::make_unique<MockResultSetSource>();
@@ -453,7 +506,8 @@ TEST(ClientTest, CommitMutatorSuccess) {
 TEST(ClientTest, CommitMutatorRollback) {
   auto conn = std::make_shared<MockConnection>();
   Transaction txn = MakeReadWriteTransaction();  // placeholder
-  Connection::ReadParams actual_read_params{txn, {}, {}, {}, {}, {}, {}, {}};
+  Connection::ReadParams actual_read_params{txn, {}, {}, {}, {},
+                                            {},  {}, {}, {}};
 
   auto source = std::make_unique<MockResultSetSource>();
   auto constexpr kText = R"pb(
@@ -495,7 +549,8 @@ TEST(ClientTest, CommitMutatorRollback) {
 TEST(ClientTest, CommitMutatorRollbackError) {
   auto conn = std::make_shared<MockConnection>();
   Transaction txn = MakeReadWriteTransaction();  // placeholder
-  Connection::ReadParams actual_read_params{txn, {}, {}, {}, {}, {}, {}, {}};
+  Connection::ReadParams actual_read_params{txn, {}, {}, {}, {},
+                                            {},  {}, {}, {}};
 
   auto source = std::make_unique<MockResultSetSource>();
   auto constexpr kText = R"pb(

google/cloud/spanner/connection.h

@@ -19,6 +19,7 @@
 #include "google/cloud/spanner/commit_options.h"
 #include "google/cloud/spanner/commit_result.h"
 #include "google/cloud/spanner/keys.h"
+#include "google/cloud/spanner/lock_hint.h"
 #include "google/cloud/spanner/mutations.h"
 #include "google/cloud/spanner/options.h"
 #include "google/cloud/spanner/partition_options.h"
@@ -81,6 +82,7 @@ class Connection {
     absl::optional<std::string> partition_token;
     bool partition_data_boost = false;  // when partition_token
     DirectedReadOption::Type directed_read_option;
+    LockHint lock_hint;
   };
 
   /// Wrap the arguments to `PartitionRead()`.

google/cloud/spanner/google_cloud_cpp_spanner.bzl

@@ -96,6 +96,7 @@ google_cloud_cpp_spanner_hdrs = [
     "interval.h",
     "json.h",
     "keys.h",
+    "lock_hint.h",
     "mutations.h",
     "numeric.h",
     "oid.h",

google/cloud/spanner/internal/connection_impl.cc

@@ -190,6 +190,21 @@ google::spanner::v1::RequestOptions_Priority ProtoRequestPriority(
   return google::spanner::v1::RequestOptions::PRIORITY_UNSPECIFIED;
 }
 
+google::spanner::v1::ReadRequest_LockHint ProtoLockHint(
+    absl::optional<spanner::LockHint> const& order_by) {
+  if (order_by) {
+    switch (*order_by) {
+      case spanner::LockHint::kLockHintUnspecified:
+        return google::spanner::v1::ReadRequest_LockHint_LOCK_HINT_UNSPECIFIED;
+      case spanner::LockHint::kLockHintShared:
+        return google::spanner::v1::ReadRequest_LockHint_LOCK_HINT_SHARED;
+      case spanner::LockHint::kLockHintExclusive:
+        return google::spanner::v1::ReadRequest_LockHint_LOCK_HINT_EXCLUSIVE;
+    }
+  }
+  return google::spanner::v1::ReadRequest_LockHint_LOCK_HINT_UNSPECIFIED;
+}
+
 // Converts a `google::protobuf::Timestamp` to a `spanner::Timestamp`, but
 // substitutes the maximal value for any conversion error. This is needed
 // when, for example, a response commit_timestamp is out of range but the
@@ -560,6 +575,7 @@ spanner::RowStream ConnectionImpl::ReadImpl(
   *request->mutable_transaction() = *s;
   request->set_table(std::move(params.table));
   request->set_index(std::move(params.read_options.index_name));
+  request->set_lock_hint(ProtoLockHint(params.lock_hint));
   for (auto&& column : params.columns) {
     request->add_columns(std::move(column));
   }

google/cloud/spanner/internal/connection_impl_test.cc

@@ -211,6 +211,10 @@ MATCHER_P(HasReplicaType, type, "has replica type") {
   return arg.type() == type;
 }
 
+MATCHER_P(HasLockHint, lock_hint, "has lock_hint") {
+  return arg.lock_hint() == lock_hint;
+}
+
 // Ideally this would be a matcher, but matcher args are `const` and `RowStream`
 // only has non-const methods.
 bool ContainsNoRows(spanner::RowStream& rows) {
@@ -4091,6 +4095,85 @@ TEST(ConnectionImplTest, RollbackSessionNotFound) {
   EXPECT_THAT(txn, HasBadSession());
 }
 
+TEST(ConnectionImplTest, ReadRequestLockHintParameterUnspecified) {
+  auto mock = std::make_shared<spanner_testing::MockSpannerStub>();
+  auto db = spanner::Database("project", "instance", "database");
+  EXPECT_CALL(*mock, BatchCreateSessions(_, _, HasDatabase(db)))
+      .WillOnce(Return(MakeSessionsResponse({"test-session-name"})));
+  EXPECT_CALL(*mock,
+              AsyncDeleteSession(_, _, _, HasSessionName("test-session-name")))
+      .WillOnce(Return(make_ready_future(Status{})));
+  Sequence s;
+  EXPECT_CALL(
+      *mock,
+      StreamingRead(
+          _, _,
+          AllOf(HasSession("test-session-name"),
+                HasLockHint(
+                    google::spanner::v1::ReadRequest::LOCK_HINT_UNSPECIFIED))))
+      .InSequence(s)
+      .WillOnce(Return(ByMove(MakeReader<google::spanner::v1::PartialResultSet>(
+          {R"pb(metadata: { transaction: { id: "txn1" } })pb"}))));
+
+  auto conn = MakeConnectionImpl(db, mock);
+  internal::OptionsSpan span(MakeLimitedTimeOptions());
+
+  // Scenario 1: No explicit OrderBy (should map to UNSPECIFIED)
+  spanner::ReadOptions read_options;
+  spanner::Transaction txn1 =
+      MakeReadOnlyTransaction(spanner::Transaction::ReadOnlyOptions());
+  auto rows1 = conn->Read(
+      {txn1, "table", spanner::KeySet::All(), {"col"}, read_options});
+  for (auto const& row : rows1) {
+    (void)row;
+  }
+  EXPECT_THAT(txn1,
+              HasSessionAndTransaction("test-session-name", "txn1", false, ""));
+}
+
+TEST(ConnectionImplTest, ReadRequestLockHintShared) {
+  auto mock = std::make_shared<spanner_testing::MockSpannerStub>();
+  auto db = spanner::Database("project", "instance", "database");
+  EXPECT_CALL(*mock, BatchCreateSessions(_, _, HasDatabase(db)))
+      .WillOnce(Return(MakeSessionsResponse({"test-session-name"})));
+  EXPECT_CALL(*mock,
+              AsyncDeleteSession(_, _, _, HasSessionName("test-session-name")))
+      .WillOnce(Return(make_ready_future(Status{})));
+  Sequence s;
+  EXPECT_CALL(
+      *mock,
+      StreamingRead(
+          _, _,
+          AllOf(
+              HasSession("test-session-name"),
+              HasLockHint(google::spanner::v1::ReadRequest::LOCK_HINT_SHARED))))
+      .InSequence(s)
+      .WillOnce(Return(ByMove(MakeReader<google::spanner::v1::PartialResultSet>(
+          {R"pb(metadata: { transaction: { id: "txn1" } })pb"}))));
+
+  auto conn = MakeConnectionImpl(db, mock);
+  internal::OptionsSpan span(MakeLimitedTimeOptions());
+  spanner::ReadOptions read_options;
+  spanner::Transaction txn1 =
+      MakeReadOnlyTransaction(spanner::Transaction::ReadOnlyOptions());
+  auto read_params =
+      spanner::Connection::ReadParams{txn1,
+                                      "table",
+                                      spanner::KeySet::All(),
+                                      {"col"},
+                                      read_options,
+                                      absl::nullopt,
+                                      false,
+                                      spanner::DirectedReadOption::Type{},
+                                      spanner::LockHint::kLockHintShared};
+  auto rows1 = conn->Read(read_params);
+  for (auto const& row : rows1) {
+    (void)row;
+  }
+  EXPECT_THAT(txn1,
+              HasSessionAndTransaction("test-session-name", "txn1", false, ""));
+}
+
 TEST(ConnectionImplTest, OperationsFailOnInvalidatedTransaction) {
   auto mock = std::make_shared<spanner_testing::MockSpannerStub>();
   auto db = spanner::Database("placeholder_project", "placeholder_instance",

google/cloud/spanner/lock_hint.h

@@ -0,0 +1,37 @@
+// 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
+//
+//     https://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.
+
+#ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_LOCK_HINT_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_LOCK_HINT_H
+
+#include "google/cloud/spanner/version.h"
+
+namespace google {
+namespace cloud {
+namespace spanner {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+// A lock hint mechanism for reads done within a transaction.
+enum class LockHint {
+  kLockHintUnspecified,
+  kLockHintShared,
+  kLockHintExclusive,
+};
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace spanner
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_LOCK_HINT_H

google/cloud/spanner/options.h

@@ -41,6 +41,7 @@
 #include "google/cloud/spanner/backoff_policy.h"
 #include "google/cloud/spanner/directed_read_replicas.h"
 #include "google/cloud/spanner/internal/session.h"
+#include "google/cloud/spanner/lock_hint.h"
 #include "google/cloud/spanner/polling_policy.h"
 #include "google/cloud/spanner/request_priority.h"
 #include "google/cloud/spanner/retry_policy.h"
@@ -195,6 +196,16 @@ struct SessionPoolActionOnExhaustionOption {
   using Type = spanner::ActionOnExhaustion;
 };
 
+/**
+ * Option for `google::cloud::Options` to set the lock hint mechanism for reads
+ * done within a transaction.
+ *
+ * @ingroup google-cloud-spanner-options
+ */
+struct LockHintOption {
+  using Type = spanner::LockHint;
+};
+
 /**
  * Option for `google::cloud::Options` to set the interval at which we refresh
  * sessions so they don't get collected by the backend GC.