feat(spanner): define IsolationLevel enum for Spanner transactions

google/cloud/spanner/CMakeLists.txt

@@ -173,6 +173,7 @@ add_library(
     internal/tuple_utils.h
     interval.cc
     interval.h
+    isolation_level.h
     json.h
     keys.cc
     keys.h

google/cloud/spanner/google_cloud_cpp_spanner.bzl

@@ -94,6 +94,7 @@ google_cloud_cpp_spanner_hdrs = [
     "internal/transaction_impl.h",
     "internal/tuple_utils.h",
     "interval.h",
+    "isolation_level.h",
     "json.h",
     "keys.h",
     "lock_hint.h",

google/cloud/spanner/integration_tests/client_integration_test.cc

@@ -16,6 +16,7 @@
 #include "google/cloud/spanner/client.h"
 #include "google/cloud/spanner/database.h"
 #include "google/cloud/spanner/mutations.h"
+#include "google/cloud/spanner/isolation_level.h"
 #include "google/cloud/spanner/options.h"
 #include "google/cloud/spanner/testing/database_integration_test.h"
 #include "google/cloud/credentials.h"
@@ -240,6 +241,25 @@ TEST_F(ClientIntegrationTest, MultipleInserts) {
                                    RowType(4, "test-fname-4", "test-lname-4")));
 }
 
+/// @test Verify that TransactionIsolationLevel works as expected.
+TEST_F(ClientIntegrationTest, TransactionIsolationLevel) {
+  auto& client = *client_;
+  auto commit = client.Commit(
+      [&](Transaction const& txn) -> StatusOr<Mutations> {
+        // Perform a read to ensure the transaction is active on the server.
+        auto rows = client.ExecuteQuery(txn, SqlStatement("SELECT 1"));
+        for (auto const& row : rows) {
+          if (!row) return row.status();
+        }
+        // std::cout << "Transaction is active." << std::endl;
+        return Mutations{};
+      },
+      Options{}.set<TransactionIsolationLevelOption>(
+          IsolationLevel::kRepeatableRead));
+  EXPECT_THAT(commit, StatusIs(StatusCode::kOk));
+}
+
+
 /// @test Verify that Client::Rollback works as expected.
 TEST_F(ClientIntegrationTest, TransactionRollback) {
   ASSERT_NO_FATAL_FAILURE(InsertTwoSingers());
@@ -1393,6 +1413,22 @@ TEST_F(PgClientIntegrationTest, FineGrainedAccessControl) {
   ASSERT_STATUS_OK(metadata);
 }
 
+/// @test Verify that TransactionIsolationLevel works as expected.
+TEST_F(PgClientIntegrationTest, TransactionIsolationLevel) {
+  auto& client = *client_;
+  auto commit = client.Commit(
+      [&](Transaction const& txn) -> StatusOr<Mutations> {
+        auto rows = client.ExecuteQuery(txn, SqlStatement("SELECT 1"));
+        for (auto const& row : rows) {
+          if (!row) return row.status();
+        }
+        return Mutations{};
+      },
+      Options{}.set<TransactionIsolationLevelOption>(
+          IsolationLevel::kRepeatableRead));
+  EXPECT_THAT(commit, StatusIs(StatusCode::kOk));
+}
+
 /// @test Verify "FOREIGN KEY" "ON DELETE CASCADE".
 TEST_F(ClientIntegrationTest, ForeignKeyDeleteCascade) {
   spanner_admin::DatabaseAdminClient admin_client(

google/cloud/spanner/isolation_level.h

@@ -0,0 +1,43 @@
+// google/cloud/spanner/isolation_level.h
+//
+// 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_ISOLATION_LEVEL_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ISOLATION_LEVEL_H
+
+#include "google/cloud/spanner/version.h"
+
+namespace google {
+namespace cloud {
+namespace spanner {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+/**
+ * The isolation level for read-write transactions.
+ *
+ * @see https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.TransactionOptions.IsolationLevel
+ */
+enum class IsolationLevel {
+  kUnspecified = 0,
+  kSerializable = 1,
+  kRepeatableRead = 2,
+};
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace spanner
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_ISOLATION_LEVEL_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/isolation_level.h"
 #include "google/cloud/spanner/lock_hint.h"
 #include "google/cloud/spanner/order_by.h"
 #include "google/cloud/spanner/polling_policy.h"
@@ -425,6 +426,16 @@ struct CommitReturnStatsOption {
   using Type = bool;
 };
 
+/**
+ * Option for `google::cloud::Options` to set the isolation level for
+ * read-write transactions.
+ *
+ * @ingroup google-cloud-spanner-options
+ */
+struct TransactionIsolationLevelOption {
+  using Type = IsolationLevel;
+};
+
 /**
  * Option for `google::cloud::Options` to set the amount of latency this request
  * is willing to incur in order to improve throughput. If this field is not set,

google/cloud/spanner/transaction.cc

@@ -62,13 +62,22 @@ google::spanner::v1::TransactionOptions MakeOpts(
 }
 
 google::spanner::v1::TransactionOptions MakeOpts(
-    google::spanner::v1::TransactionOptions_ReadWrite rw_opts) {
+    google::spanner::v1::TransactionOptions_ReadWrite rw_opts,
+    IsolationLevel isolation_level) {
   google::spanner::v1::TransactionOptions opts;
   *opts.mutable_read_write() = std::move(rw_opts);
   auto const& current = internal::CurrentOptions();
   if (current.get<ExcludeTransactionFromChangeStreamsOption>()) {
     opts.set_exclude_txn_from_change_streams(true);
   }
+  if (isolation_level == IsolationLevel::kUnspecified) {
+    isolation_level = current.get<TransactionIsolationLevelOption>();
+  }
+  if (isolation_level != IsolationLevel::kUnspecified) {
+    opts.set_isolation_level(
+        static_cast<google::spanner::v1::TransactionOptions::IsolationLevel>(
+            isolation_level));
+  }
   return opts;
 }
 
@@ -129,7 +138,8 @@ Transaction::Transaction(ReadOnlyOptions opts) {
 
 Transaction::Transaction(ReadWriteOptions opts) {
   google::spanner::v1::TransactionSelector selector;
-  *selector.mutable_begin() = MakeOpts(std::move(opts.rw_opts_));
+  *selector.mutable_begin() =
+      MakeOpts(std::move(opts.rw_opts_), opts.isolation_level_);
   auto const route_to_leader = true;  // read-write
   impl_ = std::make_shared<spanner_internal::TransactionImpl>(
       std::move(selector), route_to_leader,
@@ -138,7 +148,8 @@ Transaction::Transaction(ReadWriteOptions opts) {
 
 Transaction::Transaction(Transaction const& txn, ReadWriteOptions opts) {
   google::spanner::v1::TransactionSelector selector;
-  *selector.mutable_begin() = MakeOpts(std::move(opts.rw_opts_));
+  *selector.mutable_begin() =
+      MakeOpts(std::move(opts.rw_opts_), opts.isolation_level_);
   auto const route_to_leader = true;  // read-write
   impl_ = std::make_shared<spanner_internal::TransactionImpl>(
       *txn.impl_, std::move(selector), route_to_leader,
@@ -155,7 +166,8 @@ Transaction::Transaction(SingleUseOptions opts) {
 
 Transaction::Transaction(ReadWriteOptions opts, SingleUseCommitTag) {
   google::spanner::v1::TransactionSelector selector;
-  *selector.mutable_single_use() = MakeOpts(std::move(opts.rw_opts_));
+  *selector.mutable_single_use() =
+      MakeOpts(std::move(opts.rw_opts_), opts.isolation_level_);
   auto const route_to_leader = true;  // write
   impl_ = std::make_shared<spanner_internal::TransactionImpl>(
       std::move(selector), route_to_leader,

google/cloud/spanner/transaction.h

@@ -18,6 +18,7 @@
 #include "google/cloud/spanner/internal/transaction_impl.h"
 #include "google/cloud/spanner/timestamp.h"
 #include "google/cloud/spanner/version.h"
+#include "google/cloud/spanner/isolation_level.h"
 #include "absl/types/optional.h"
 #include <google/spanner/v1/transaction.pb.h>
 #include <chrono>
@@ -103,10 +104,16 @@ class Transaction {
     // A tag used for collecting statistics about the transaction.
     ReadWriteOptions& WithTag(absl::optional<std::string> tag);
 
+    ReadWriteOptions& WithIsolationLevel(IsolationLevel isolation_level) {
+      isolation_level_ = isolation_level;
+      return *this;
+    }
+
    private:
     friend Transaction;
     google::spanner::v1::TransactionOptions_ReadWrite rw_opts_;
     absl::optional<std::string> tag_;
+    IsolationLevel isolation_level_ = IsolationLevel::kUnspecified;
   };
 
   /**

google/cloud/spanner/transaction_test.cc

@@ -14,6 +14,8 @@
 
 #include "google/cloud/spanner/transaction.h"
 #include "google/cloud/spanner/internal/session.h"
+#include "google/cloud/spanner/options.h"
+#include "google/cloud/options.h"
 #include <gmock/gmock.h>
 
 namespace google {
@@ -169,6 +171,59 @@ TEST(Transaction, MultiplexedPreviousTransactionId) {
       });
 }
 
+TEST(Transaction, IsolationLevel) {
+  auto opts = Transaction::ReadWriteOptions().WithIsolationLevel(
+      IsolationLevel::kRepeatableRead);
+  Transaction txn = MakeReadWriteTransaction(opts);
+  spanner_internal::Visit(
+      txn, [](spanner_internal::SessionHolder&,
+              StatusOr<google::spanner::v1::TransactionSelector>& s,
+              spanner_internal::TransactionContext const&) {
+        EXPECT_TRUE(s->has_begin());
+        EXPECT_TRUE(s->begin().has_read_write());
+        EXPECT_EQ(s->begin().isolation_level(),
+                  google::spanner::v1::TransactionOptions::REPEATABLE_READ);
+
+        std::cout << "Isolation Level: "
+                  << s->begin().isolation_level() << std::endl;
+        return 0;
+      });
+}
+
+TEST(Transaction, IsolationLevelPrecedence) {
+  internal::OptionsSpan span(Options{}.set<TransactionIsolationLevelOption>(
+      IsolationLevel::kSerializable));
+
+  // Case 1: Per-call overrides client default
+  auto opts = Transaction::ReadWriteOptions().WithIsolationLevel(
+      IsolationLevel::kRepeatableRead);
+  Transaction txn = MakeReadWriteTransaction(opts);
+  spanner_internal::Visit(
+      txn, [](spanner_internal::SessionHolder&,
+              StatusOr<google::spanner::v1::TransactionSelector>& s,
+              spanner_internal::TransactionContext const&) {
+        EXPECT_EQ(s->begin().isolation_level(),
+                  google::spanner::v1::TransactionOptions::REPEATABLE_READ);
+        std::cout << "Isolation Level: "
+                  << s->begin().isolation_level() << std::endl;
+        return 0;
+      });
+
+  // Case 2: Fallback to client default
+  auto opts_default = Transaction::ReadWriteOptions();
+  Transaction txn_default = MakeReadWriteTransaction(opts_default);
+  spanner_internal::Visit(
+      txn_default, [](spanner_internal::SessionHolder&,
+                      StatusOr<google::spanner::v1::TransactionSelector>& s,
+                      spanner_internal::TransactionContext const&) {
+        EXPECT_EQ(s->begin().isolation_level(),
+                  google::spanner::v1::TransactionOptions::SERIALIZABLE);
+        std::cout << "Isolation Level: "
+                  << s->begin().isolation_level() << std::endl;
+        return 0;
+      });
+}
+
 TEST(Transaction, ReadWriteOptionsWithTag) {
   auto opts = Transaction::ReadWriteOptions().WithTag("test-tag");
   Transaction txn = MakeReadWriteTransaction(opts);