feat(spanner): A new enum IsolationLevel is added

Google APIs · copybara-github · commit 516ab0ae2f74 · 2025-02-20T15:04:26.000-08:00
feat(spanner): A new field `isolation_level` is added to message `.google.spanner.v1.TransactionOptions`
docs(spanner): A comment for enum value `READ_LOCK_MODE_UNSPECIFIED` in enum `ReadLockMode` is changed
docs(spanner): A comment for enum value `PESSIMISTIC` in enum `ReadLockMode` is changed
docs(spanner): A comment for enum value `OPTIMISTIC` in enum `ReadLockMode` is changed

PiperOrigin-RevId: 729265828
diff --git a/google/spanner/v1/transaction.proto b/google/spanner/v1/transaction.proto
@@ -361,19 +361,31 @@ message TransactionOptions {
     enum ReadLockMode {
       // Default value.
       //
-      // If the value is not specified, the pessimistic read lock is used.
+      // * If isolation level is `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 for:
+      //     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
+      //   to validate that the data that was served at the snapshot time is
+      //   unchanged at commit time.
+      // * At all other isolation levels, if `read_lock_mode` is the default
+      //   value, then pessimistic read lock is used.
       READ_LOCK_MODE_UNSPECIFIED = 0;
 
       // Pessimistic lock mode.
       //
       // Read locks are acquired immediately on read.
+      // Semantics described only applies to `SERIALIZABLE` isolation.
       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 `SERIALIZABLE` isolation.
       OPTIMISTIC = 2;
     }
 
@@ -461,6 +473,38 @@ message TransactionOptions {
     bool return_read_timestamp = 6;
   }
 
+  // `IsolationLevel` is used when setting `isolation_level` for a transaction.
+  enum IsolationLevel {
+    // Default value.
+    //
+    // If the value is not specified, the `SERIALIZABLE` isolation level is
+    // used.
+    ISOLATION_LEVEL_UNSPECIFIED = 0;
+
+    // All transactions appear as if they executed in a serial order, even if
+    // some of the reads, writes, and other operations of distinct transactions
+    // actually occurred in parallel. Spanner assigns commit timestamps that
+    // reflect the order of committed transactions to implement this property.
+    // Spanner offers a stronger guarantee than serializability called external
+    // consistency. For further details, please refer to
+    // https://cloud.google.com/spanner/docs/true-time-external-consistency#serializability.
+    SERIALIZABLE = 1;
+
+    // All reads performed during the transaction observe a consistent snapshot
+    // of the database, and the transaction will only successfully commit in the
+    // absence of conflicts between its updates and any concurrent updates that
+    // have occurred since that snapshot. Consequently, in contrast to
+    // `SERIALIZABLE` transactions, only write-write conflicts are detected in
+    // snapshot transactions.
+    //
+    // This isolation level does not support Read-only and Partitioned DML
+    // transactions.
+    //
+    // When `REPEATABLE_READ` is specified on a read-write transaction, the
+    // locking semantics default to `OPTIMISTIC`.
+    REPEATABLE_READ = 2;
+  }
+
   // Required. The type of transaction.
   oneof mode {
     // Transaction may write.
@@ -500,6 +544,9 @@ message TransactionOptions {
   // partitioned-dml transactions, otherwise the API will return an
   // `INVALID_ARGUMENT` error.
   bool exclude_txn_from_change_streams = 5;
+
+  // Isolation level for the transaction.
+  IsolationLevel isolation_level = 6;
 }
 
 // A transaction.
