feat(spanner): define IsolationLevel enum for Spanner transactions #15853

prathmeshcc · 2026-01-05T19:08:12Z

This PR introduces support for snapshot isolation levels in Spanner transactions, enabling users to specify REPEATABLE_READ for read-write transactions. This provides more granular control over transaction semantics, allowing for a different trade-off between consistency and performance compared to the default SERIALIZABLE level.

Addressing Reviewer Feedback

Based on initial feedback, the API design has been refined to improve clarity and type safety. IsolationLevel is now configured exclusively through Transaction::ReadWriteOptions. This ensures that the setting is only applied in the context of a read-write transaction, which is its only valid use case, preventing potential misuse.

Key Changes:

A new Transaction::IsolationLevel enum is introduced with kSerializable and kRepeatableRead values.
Transaction::ReadWriteOptions is enhanced with a WithIsolationLevel() method, providing a fluent API for configuration.
The previous Transaction constructor that accepted a separate IsolationLevel has been removed in favor of this more explicit, options-based approach.
Unit tests have been updated to verify that the selected isolation level is correctly propagated to the Spanner backend.

gemini-code-assist · 2026-01-05T19:08:37Z

Summary of Changes

Hello @prathmeshcc, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the Google Cloud Spanner C++ client library by introducing explicit support for transaction isolation levels. It defines a new IsolationLevel enum and integrates it into the transaction options, allowing users to configure the desired isolation behavior, such as Repeatable Read, for their read-write transactions. This change lays the groundwork for more granular control over transaction semantics.

Highlights

New IsolationLevel Enum: Introduced google::cloud::spanner::IsolationLevel enum class, mirroring google.spanner.v1.TransactionOptions.IsolationLevel with kUnspecified, kSerializable, and kRepeatableRead.
Configurable Transaction Isolation: Added the ability to specify the isolation level for read-write transactions through Transaction::ReadWriteOptions and TransactionIsolationLevelOption.
Integration and Unit Tests: Included new integration tests in client_integration_test.cc and unit tests in transaction_test.cc to validate the correct application and precedence of isolation levels.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces an IsolationLevel enum and the corresponding TransactionIsolationLevelOption to allow users to configure the isolation level for read-write transactions. The changes are well-structured and follow existing patterns in the codebase. The new functionality is well-tested with new unit and integration tests that verify the option handling and precedence. The implementation appears correct and complete. I have one minor suggestion to remove some debugging output from the unit tests.

google/cloud/spanner/transaction_test.cc

codecov · 2026-01-05T20:10:18Z

Codecov Report

❌ Patch coverage is 92.68293% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.94%. Comparing base (752f0ed) to head (72ec605).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
google/cloud/spanner/transaction.cc	86.36%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #15853      +/-   ##
==========================================
- Coverage   92.95%   92.94%   -0.01%     
==========================================
  Files        2458     2458              
  Lines      227974   228012      +38     
==========================================
+ Hits       211903   211935      +32     
- Misses      16071    16077       +6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

devbww · 2026-01-05T19:55:47Z

google/cloud/spanner/transaction.cc

+    opts.set_isolation_level(
+        static_cast<google::spanner::v1::TransactionOptions::IsolationLevel>(
+            isolation_level));


We strive to not tie the C++ enum values to the protobuf enum values. See, for example, LockHint, OrderBy, ReadLockMode, ReplicaType, RequestPriority, etc. Please continue that by introducing an explicit mapping here (removing the static_cast and specific enum class values).

google/cloud/spanner/integration_tests/client_integration_test.cc

devbww · 2026-01-05T20:23:14Z

google/cloud/spanner/integration_tests/client_integration_test.cc

+        // std::cout << "Transaction is active." << std::endl;
+        return Mutations{};
+      },
+      Options{}.set<TransactionIsolationLevelOption>(


Would this test behave any differently if this was ignored? That is, what are we testing?

You're right that this test would pass with the default isolation level. Its purpose is to act as a smoke test to ensure the TransactionIsolationLevelOption is correctly serialized by the client and accepted by the backend without errors. I've added a comment to make this intent clear.

devbww · 2026-01-05T20:23:38Z

google/cloud/spanner/integration_tests/client_integration_test.cc

+        }
+        return Mutations{};
+      },
+      Options{}.set<TransactionIsolationLevelOption>(


devbww · 2026-01-05T20:33:35Z

google/cloud/spanner/transaction.cc

+  *selector.mutable_begin() =
+      MakeOpts(std::move(opts.rw_opts_), opts.isolation_level_);


[GitHub seems to have dropped a comment here. Apologies if you see this twice.]

It seems weird that the isolation level appears to only be useful in read-write mode yet it wasn't made part of message ReadWrite. Is that appearance true (and the protos should probably be fixed, in which case we would not need any special treatment here), or are we being too specific in making the isolation mode a member of ReadWriteOptions?

You're correct, Transaction isolation levels are only meaningful for read-write transactions.

The original implementation was a bit too general. It allowed IsolationLevel to be passed in contexts where it didn't apply, which could be confusing.

My latest changes address this directly. I have moved isolation_level_ to be a private member of Transaction::ReadWriteOptions. This tightens up the API and makes the class structure more accurately reflect the constraints of the underlying Spanner API. The Transaction constructor now correctly pulls the isolation level from the ReadWriteOptions struct, ensuring it's only ever configured in the correct context.

OK. If there is no chance to correct the proto definition, then we should certainly make sure that a comment is added to clarify that isolation_level only applies to the ReadWrite mode.

This commit improves the API design by integrating `IsolationLevel` directly into `Transaction::ReadWriteOptions`. Previously, `IsolationLevel` was passed as a separate argument to some `Transaction` constructors, even though it is semantically relevant only to read-write transactions. This could lead to ambiguity or misuse. By making `IsolationLevel` a member of `ReadWriteOptions`, the API more accurately reflects the underlying Spanner transaction semantics, enforcing that isolation levels are configured solely within the context of read-write transactions. This enhances type safety and improves the clarity of the client library's API. This change addresses reviewer feedback regarding the logical grouping of `IsolationLevel` within the `ReadWriteOptions` message.#

google/cloud/spanner/transaction.h

google/cloud/spanner/options.h

scotthart · 2026-01-12T22:26:05Z

google/cloud/spanner/transaction.cc

+      *isolation_level != Transaction::IsolationLevel::kUnspecified) {
+    opts.set_isolation_level(ProtoIsolationLevel(isolation_level));
+  } else if (current.has<TransactionIsolationLevelOption>()) {
+    opts.set_isolation_level(


Remove this else if block since we're removing TransactionIsolationLevelOption.

Since we will provide this option for consistency, we need to include this.

scotthart · 2026-01-12T22:29:41Z

google/cloud/spanner/transaction.cc

+}
+
+Transaction::Transaction(ReadWriteOptions opts,
+                         IsolationLevel isolation_level) {


IsolationLevel is present as a member field of ReadWriteOptions, we shouldn't need to duplicate it in the parameters in a new constructor.

devbww

This PR introduces the IsolationLevel enum class in google/cloud/spanner/isolation_level.h.

Update the PR description to reflect the state of the PR.

google/cloud/spanner/integration_tests/client_integration_test.cc

google/cloud/spanner/options.h

devbww · 2026-01-12T23:36:39Z

google/cloud/spanner/transaction.cc

    opts.set_exclude_txn_from_change_streams(true);
  }
+  if (isolation_level &&
+      *isolation_level != Transaction::IsolationLevel::kUnspecified) {


Why make this extra guard when we don't do the same thing when current is unspecified?

Without the *isolation_level != Transaction::IsolationLevel::kUnspecified check, if you passed in kUnspecified, the first part of the if (isolation_level) would be true, and the code would set the isolation level to "unspecified", ignoring any default that might have been set on the client.

devbww · 2026-01-12T23:40:23Z

google/cloud/spanner/transaction.cc

+  *selector.mutable_begin() =
+      MakeOpts(std::move(opts.rw_opts_), opts.isolation_level_);


OK. If there is no chance to correct the proto definition, then we should certainly make sure that a comment is added to clarify that isolation_level only applies to the ReadWrite mode.

google/cloud/spanner/transaction.cc

google/cloud/spanner/transaction.h

devbww · 2026-01-12T23:45:53Z

google/cloud/spanner/transaction_test.cc

      google::spanner::v1::TransactionOptions_ReadWrite::OPTIMISTIC);
 }

+TEST(Transaction, ReadWriteOptionsWithIsolationLevel) {


How is this any different from Transaction.IsolationLevel?

TEST(Transaction, ReadWriteOptionsWithIsolationLevel) was indeed testing the same code path as TEST(Transaction, IsolationLevel). It was specifically targeting the constructor Transaction(ReadWriteOptions, IsolationLevel), which has been removed as part of addressing the previous comment.

devbww · 2026-01-12T23:46:55Z

google/cloud/spanner/transaction_test.cc

      });
 }

+TEST(Transaction, IsolationLevel) {


How is this any different from Transaction.IsolationLevelPrecedence case 1?

The purpose of this test is to check the basic correctness of establishing a Transaction, but I removed it since the Transaction.IsolationLevelPrecedence does that anyways.

This commit refines the API design by integrating `IsolationLevel` directly into `Transaction::ReadWriteOptions`. Previously, `IsolationLevel` was passed as a separate argument to some `Transaction` constructors, even though it is semantically relevant only to read-write transactions. This could lead to ambiguity or misuse. These changes address reviewer feedback, enforcing that isolation levels are configured solely within the context of read-write transactions. This enhances type safe and improves the clarity of the client library's API. Key changes include: - Removing the `IsolationLevel` parameter from `Transaction` constructors, as it is now configured via `ReadWriteOptions`. - Enhancing `Transaction::ReadWriteOptions` with a `WithIsolationLevel` method, allowing for a fluent configuration of the desired isolation level (e.g., `kSerializable`, `kRepeatableRead`). - Updating internal transaction handling logic to correctly propagate the selected isolation level from `ReadWriteOptions` to the Spanner backend.

google/cloud/spanner/transaction.h

@note

Changed "Note:" to "@note" in the Doxygen documentation for `Transaction::IsolationLevel` to use the correct Doxygen tag. This improves consistency and ensures proper rendering of the documentation.

product-auto-label bot added the api: spanner Issues related to the Spanner API. label Jan 5, 2026

prathmeshcc temporarily deployed to false January 5, 2026 19:08 — with GitHub Actions Inactive

gemini-code-assist bot reviewed Jan 5, 2026

View reviewed changes

google/cloud/spanner/transaction_test.cc Outdated Show resolved Hide resolved

devbww reviewed Jan 5, 2026

View reviewed changes

prathmeshcc force-pushed the feat/spanner-isolation-level branch from ceb7ee6 to b89fdd9 Compare January 12, 2026 17:38

prathmeshcc marked this pull request as ready for review January 12, 2026 17:48

prathmeshcc requested a review from a team as a code owner January 12, 2026 17:48

prathmeshcc added 2 commits January 12, 2026 19:10

feat(spanner): add support for snapshot isolation

e7407c6

prathmeshcc force-pushed the feat/spanner-isolation-level branch from b89fdd9 to 7451e09 Compare January 12, 2026 19:16

scotthart requested changes Jan 12, 2026

View reviewed changes

devbww reviewed Jan 12, 2026

View reviewed changes

scotthart requested changes Jan 14, 2026

View reviewed changes

google/cloud/spanner/transaction.h Show resolved Hide resolved

prathmeshcc added 2 commits January 14, 2026 19:02

docs(spanner): update Doxygen tag for Transaction::IsolationLevel

0bc80ae

Changed "Note:" to "@note" in the Doxygen documentation for `Transaction::IsolationLevel` to use the correct Doxygen tag. This improves consistency and ensures proper rendering of the documentation.

Merge branch 'main' into feat/spanner-isolation-level

55a7f27

scotthart approved these changes Jan 14, 2026

View reviewed changes

		*selector.mutable_begin() =
		MakeOpts(std::move(opts.rw_opts_), opts.isolation_level_);

feat(spanner): define IsolationLevel enum for Spanner transactions #15853

Are you sure you want to change the base?

feat(spanner): define IsolationLevel enum for Spanner transactions #15853

Conversation

prathmeshcc commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Jan 5, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

codecov bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devbww left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

prathmeshcc commented Jan 5, 2026 •

edited

Loading

codecov bot commented Jan 5, 2026 •

edited

Loading