google-cloud-spanner 2.29.0 → 2.31.0

data/lib/google/cloud/spanner/transaction.rb

@@ -97,19 +97,42 @@ module Google
         # @return [::Boolean]
         attr_accessor :exclude_txn_from_change_streams
 
+        # A token that is required when committing an RW transaction over a multiplexed session
+        # It can be read when transaction is created (either by BeginTransaction or by inlined begin),
+        # or from a previous operation within existing transaction.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::MultiplexedSessionPrecommitToken, nil]
+        attr_accessor :precommit_token
+
+        # An id of the previous transaction, if this new transaction wrapper is being created
+        # as a part of a retry. Previous transaction id should be added to TransactionOptions
+        # of a new ReadWrite transaction when retry is attempted.
+        # @private
+        # @return [::String, nil]
+        attr_reader :previous_transaction_id
+
         # Creates a new `Spanner::Transaction` instance from a `V1::Transaction` object.
         # @param grpc [::Google::Cloud::Spanner::V1::Transaction] Underlying `V1::Transaction` object.
         # @param session [::Google::Cloud::Spanner::Session] The session this transaction is running in.
         # @param exclude_txn_from_change_streams [::Boolean]
         #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
         #   or write transactions from being tracked in change streams.
+        # @param previous_transaction_id [::String, nil] Optional.
+        #   An id of the previous transaction, if this new transaction wrapper is being created
+        #   as a part of a retry. Previous transaction id should be added to TransactionOptions
+        #   of a new ReadWrite transaction when retry is attempted.
         # @private
         # @return [::Google::Cloud::Spanner::Transaction]
-        def initialize grpc, session, exclude_txn_from_change_streams
+        def initialize grpc, session, exclude_txn_from_change_streams, previous_transaction_id: nil
           @grpc = grpc
           @session = session
           @exclude_txn_from_change_streams = exclude_txn_from_change_streams
 
+          # throwing away empty strings for simplicity
+          unless previous_transaction_id.nil? || previous_transaction_id.empty?
+            @previous_transaction_id = previous_transaction_id
+          end
+
           @commit = Commit.new
           @seqno = 0
           @exclude_txn_from_change_streams = false
@@ -130,6 +153,14 @@ module Google
           # create a transaction must be synchronized, and any logic that depends on
           # the state of transaction creation must also be synchronized.
           @mutex = Mutex.new
+
+          # Precommit token is a piece of server-side bookkeeping pushed onto client-side
+          # as a part of MultiplexedSession update. Briefly, for a given read-write transaction on a
+          # Multiplexed session the client library must:
+          #   1. From all read operations, store the most recently received token.
+          #   2. Include this final token in the CommitRequest.
+          # @type [::Google::Cloud::Spanner::V1::MultiplexedSessionPrecommitToken, nil]
+          @precommit_token = nil
         end
 
         ##
@@ -397,8 +428,11 @@ module Google
                                             query_options: query_options,
                                             request_options: request_options,
                                             call_options: call_options,
-                                            route_to_leader: route_to_leader
-            @grpc ||= results.transaction
+                                            route_to_leader: route_to_leader,
+                                            precommit_token_notify: method(:update_precommit_token!)
+
+            update_wrapped_transaction! results.transaction
+
             results
           end
         end
@@ -573,6 +607,11 @@ module Google
                                   query_options: query_options,
                                   request_options: request_options,
                                   call_options: call_options
+
+          # Since this method is calling `execute_query`, the transaction is going to be updated,
+          # and the `results` object is going to be set up with precommit token notification reference,
+          # so we don't need to do anything special here.
+
           # Stream all PartialResultSet to get ResultSetStats
           results.rows.to_a
           # Raise an error if there is not a row count returned
@@ -676,11 +715,59 @@ module Google
                                             request_options: request_options,
                                             call_options: call_options, &block
             batch_update_results = BatchUpdateResults.new response
-            @grpc ||= batch_update_results.transaction
+            update_wrapped_transaction! batch_update_results.transaction
+            response.result_sets.each do |result_set|
+              update_precommit_token! result_set.precommit_token if result_set.precommit_token
+            end
             batch_update_results.row_counts
           end
         end
 
+        # Updates this `Spanner::Transaction` with a new underlying `V1::Transaction` object.
+        # This happens when this `Spanner::Transaction` is in a empty-wrapper mode
+        # (it was created by `Google::Cloud::Spanner::Session#create_empty_transaction`).
+        # In that mode the inner wrapped `grpc` object representing the `V1::Transaction` is nil,
+        # and (almost all) service request run using the "inline-begin" transactions.
+        # As part of "inline-begin", a new `V1::Transaction` is created server-side, returned with the
+        # results, and in turn should be saved as the new `grpc` object.
+        #
+        # ! This method is expected to be called from within `safe_execute()` method's block!
+        #
+        # This method also updates the precommit token, if the new underlying `V1::Transaction` has it.
+        #
+        # This is a mutator method.
+        # @param new_transaction [::Google::Cloud::Spanner::V1::Transaction]
+        #   `V1::Transaction` object that was created on the server-side.
+        # @private
+        # @return [void]
+        def update_wrapped_transaction! new_transaction
+          return unless @grpc.nil?
+          return if new_transaction.nil?
+
+          @grpc = new_transaction
+          update_precommit_token! new_transaction.precommit_token
+        end
+
+        # Updates this transaction's precommit token but only if:
+        #   * new token exists
+        #   * new token's seq_num is greater.
+        #
+        # ! This method is expected to be called from within `safe_execute()` method's block!
+        #
+        # This is a mutator method.
+        # @param new_precommit_token [::Google::Cloud::Spanner::V1::MultiplexedSessionPrecommitToken, nil]
+        #   the new precommit token, if any, from the latest service operation (e.g. from a ResultSet from a read).
+        # @private
+        # @return [void]
+        def update_precommit_token! new_precommit_token
+          if !new_precommit_token.nil? && (
+              @precommit_token.nil? ||
+              new_precommit_token.seq_num > @precommit_token.seq_num
+            )
+            @precommit_token = new_precommit_token
+          end
+        end
+
         ##
         # Read rows from a database table, as a simple alternative to
         # {#execute_query}.
@@ -754,8 +841,9 @@ module Google
                                    transaction: tx_selector,
                                    request_options: request_options,
                                    call_options: call_options,
-                                   route_to_leader: route_to_leader
-            @grpc ||= results.transaction
+                                   route_to_leader: route_to_leader,
+                                   precommit_token_notify: method(:update_precommit_token!)
+            update_wrapped_transaction! results.transaction
             results
           end
         end
@@ -1143,33 +1231,9 @@ module Google
           ColumnValue.commit_timestamp
         end
 
-        ##
-        # @private
-        # Keeps the transaction current by creating a new transaction.
-        def keepalive!
-          ensure_session!
-          @grpc = session.create_transaction.instance_variable_get :@grpc
-        end
-
-        ##
-        # @private
-        # Permanently deletes the transaction and session.
-        def release!
-          ensure_session!
-          session.release!
-        end
-
-        ##
-        # @private
-        # Determines if the transaction has been idle longer than the given
-        # duration.
-        def idle_since? duration
-          session.idle_since? duration
-        end
-
-        ##
-        # @private
         # All of the mutations created in the transaction block.
+        # @private
+        # @return [Array<Google::Cloud::Spanner::V1::Mutation>]
         def mutations
           @commit.mutations
         end
@@ -1180,10 +1244,14 @@ module Google
         # @param exclude_txn_from_change_streams [::Boolean] Optional. Defaults to `false`.
         #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
         #   or write transactions from being tracked in change streams.
+        # @param previous_transaction_id [::String, nil] Optional.
+        #   An id of the previous transaction, if this new transaction wrapper is being created
+        #   as a part of a retry. Previous transaction id should be added to TransactionOptions
+        #   of a new ReadWrite transaction when retry is attempted.
         # @private
         # @return [::Google::Cloud::Spanner::Transaction]
-        def self.from_grpc grpc, session, exclude_txn_from_change_streams: false
-          new grpc, session, exclude_txn_from_change_streams
+        def self.from_grpc grpc, session, exclude_txn_from_change_streams: false, previous_transaction_id: nil
+          new grpc, session, exclude_txn_from_change_streams, previous_transaction_id: previous_transaction_id
         end
 
         ##
@@ -1211,16 +1279,27 @@ module Google
         # @return [::Google::Cloud::Spanner::V1::Transaction, nil] The new transaction
         #   object, or `nil` if a transaction already exists.
         def safe_begin_transaction! exclude_from_change_streams: false, request_options: nil, call_options: nil
+          # If a read-write transaction on a multiplexed session commit mutations
+          # without performing any reads or queries, one of the mutations from the mutation set
+          # must be sent as a mutation key for `BeginTransaction`.
+          # @type [::Google::Cloud::Spanner::V1::Mutation, nil]
+          mutation_key = mutations[0] if mutations.any?
+
           @mutex.synchronize do
             return if existing_transaction?
             ensure_session!
             route_to_leader = LARHeaders.begin_transaction true
+
+            # TODO: [virost@, 2025-10] fix this so it uses tx_selector
+            # instead of re-creating it within `Service#begin_transaction`
             @grpc = service.begin_transaction(
               session.path,
               exclude_txn_from_change_streams: exclude_from_change_streams,
               request_options: request_options,
               call_options: call_options,
-              route_to_leader: route_to_leader
+              route_to_leader: route_to_leader,
+              mutation_key: mutation_key,
+              previous_transaction_id: previous_transaction_id
             )
           end
         end
@@ -1266,9 +1345,18 @@ module Google
         # @return [::Google::Cloud::Spanner::V1::TransactionSelector]
         def tx_selector exclude_txn_from_change_streams: false
           return V1::TransactionSelector.new id: transaction_id if existing_transaction?
+
+          read_write = if @previous_transaction_id.nil?
+                         V1::TransactionOptions::ReadWrite.new
+                       else
+                         V1::TransactionOptions::ReadWrite.new(
+                           multiplexed_session_previous_transaction_id: @previous_transaction_id
+                         )
+                       end
+
           V1::TransactionSelector.new(
             begin: V1::TransactionOptions.new(
-              read_write: V1::TransactionOptions::ReadWrite.new,
+              read_write: read_write,
               exclude_txn_from_change_streams: exclude_txn_from_change_streams
             )
           )

data/lib/google/cloud/spanner/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.29.0".freeze
+      VERSION = "2.31.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.29.0
+  version: 2.31.0
 platform: ruby
 authors:
 - Mike Moore
@@ -161,6 +161,8 @@ files:
 - lib/google/cloud/spanner/results.rb
 - lib/google/cloud/spanner/service.rb
 - lib/google/cloud/spanner/session.rb
+- lib/google/cloud/spanner/session_cache.rb
+- lib/google/cloud/spanner/session_creation_options.rb
 - lib/google/cloud/spanner/snapshot.rb
 - lib/google/cloud/spanner/status.rb
 - lib/google/cloud/spanner/transaction.rb