google-cloud-spanner 2.17.0 → 2.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc70eb07f76250946af950e0dae045072c767ed0fa1be9c2f983c24f4730679a
-  data.tar.gz: d8faa1c37467724ed5227dcea972c0da233b56e1cf88354ff084c8394792b6ea
+  metadata.gz: 37f9332aedaf9d53b1eb13596dafa4b3571393449b85ce5e63750b5c57381e3f
+  data.tar.gz: b137394c7819e4795a98727e626772ece2404ef40bc7ef84153014768ddbfb89
 SHA512:
-  metadata.gz: 84ceadbf10e41390c371177d5fedfb846ea83e2eabd0017b94f83a08b9ded5fff51de65f64c3cd7ee52112066593a156fb944d8b895f18665f1f90aec53dbf17
-  data.tar.gz: 226d5e9d43e373aa736ea58f0b4fe49ea846f995996f91448fbf387b2ba12e574c91c5bf313d37a0625324b725de46a3eee7092cbded4e23b1c6956a1674c48d
+  metadata.gz: 0ea41265627415904e066549390d59ad72a2be577c3b6f7ac67d8a47197e4f2df4a79f9c2c14735bcd383989b2f3bfa602fe68e3ebde1d7cc055252d8644f36f
+  data.tar.gz: 2cc9bf3bbe521e85c72ad2dd255eedf09225c0bbcc67bc4c319a4036aa7beac01c18f73a0fb6ff1fd203b96b15ff2b3bcbb82f2f8ddfd0f2aa72e1d2f31f03e9

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 2.18.0 (2023-09-05)
+
+#### Features
+
+* Implement "Inline Begin Transaction" ([#54](https://github.com/googleapis/ruby-spanner/issues/54)) 
+
 ### 2.17.0 (2023-06-23)
 
 #### Features

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

@@ -0,0 +1,50 @@
+# Copyright 2023 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.
+
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # @private Helper class to process BatchDML response
+      class BatchUpdateResults
+        ## Object of type
+        # Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse
+        attr_reader :grpc
+
+        def initialize grpc
+          @grpc = grpc
+        end
+
+        def row_counts
+          if @grpc.status.code.zero?
+            @grpc.result_sets.map { |rs| rs.stats.row_count_exact }
+          else
+            begin
+              raise Google::Cloud::Error.from_error @grpc.status
+            rescue Google::Cloud::Error
+              raise Google::Cloud::Spanner::BatchUpdateError.from_grpc @grpc
+            end
+          end
+        end
+
+        ##
+        # Returns transaction if available. Otherwise returns nil
+        def transaction
+          @grpc&.result_sets&.first&.metadata&.transaction
+        end
+      end
+    end
+  end
+end

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

@@ -49,6 +49,10 @@ module Google
       #   end
       #
       class Client
+        ##
+        # @private
+        IS_TRANSACTION_RUNNING_KEY = "ruby_spanner_is_transaction_running".freeze
+
         ##
         # @private Creates a new Spanner Client instance.
         def initialize project, instance_id, database_id, session_labels: nil,
@@ -1634,6 +1638,7 @@ module Google
         # rubocop:disable Metrics/MethodLength
         # rubocop:disable Metrics/BlockLength
 
+
         ##
         # Creates a transaction for reads and writes that execute atomically at
         # a single logical point in time across columns, rows, and tables in a
@@ -1788,7 +1793,7 @@ module Google
         def transaction deadline: 120, commit_options: nil,
                         request_options: nil, call_options: nil
           ensure_service!
-          unless Thread.current[:transaction_id].nil?
+          unless Thread.current[IS_TRANSACTION_RUNNING_KEY].nil?
             raise "Nested transactions are not allowed"
           end
 
@@ -1799,17 +1804,20 @@ module Google
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
-          @pool.with_transaction do |tx|
+          @pool.with_session do |session|
+            tx = session.create_empty_transaction
             if request_options
               tx.transaction_tag = request_options[:transaction_tag]
             end
 
             begin
-              Thread.current[:transaction_id] = tx.transaction_id
+              Thread.current[IS_TRANSACTION_RUNNING_KEY] = true
               yield tx
+              transaction_id = nil
+              transaction_id = tx.transaction_id if tx.existing_transaction?
               commit_resp = @project.service.commit \
                 tx.session.path, tx.mutations,
-                transaction_id: tx.transaction_id,
+                transaction_id: transaction_id,
                 commit_options: commit_options,
                 request_options: request_options,
                 call_options: call_options
@@ -1819,28 +1827,21 @@ module Google
                    Google::Cloud::AbortedError,
                    GRPC::Internal,
                    Google::Cloud::InternalError => e
-              raise e if internal_error_and_not_retryable? e
-              # Re-raise if deadline has passed
-              if current_time - start_time > deadline
-                if e.is_a? GRPC::BadStatus
-                  e = Google::Cloud::Error.from_error e
-                end
-                raise e
-              end
+              check_and_propagate_err! e, (current_time - start_time > deadline)
               # Sleep the amount from RetryDelay, or incremental backoff
               sleep(delay_from_aborted(e) || backoff *= 1.3)
               # Create new transaction on the session and retry the block
-              tx = tx.session.create_transaction
+              tx = session.create_transaction
               retry
             rescue StandardError => e
               # Rollback transaction when handling unexpected error
-              tx.session.rollback tx.transaction_id
+              tx.session.rollback tx.transaction_id if tx.existing_transaction?
               # Return nil if raised with rollback.
               return nil if e.is_a? Rollback
               # Re-raise error.
               raise e
             ensure
-              Thread.current[:transaction_id] = nil
+              Thread.current[IS_TRANSACTION_RUNNING_KEY] = nil
             end
           end
         end
@@ -1923,7 +1924,7 @@ module Google
                                   exact_staleness: exact_staleness
 
           ensure_service!
-          unless Thread.current[:transaction_id].nil?
+          unless Thread.current[IS_TRANSACTION_RUNNING_KEY].nil?
             raise "Nested snapshots are not allowed"
           end
 
@@ -1933,11 +1934,11 @@ module Google
                             timestamp: (timestamp || read_timestamp),
                             staleness: (staleness || exact_staleness),
                             call_options: call_options
-            Thread.current[:transaction_id] = snp_grpc.id
+            Thread.current[IS_TRANSACTION_RUNNING_KEY] = true
             snp = Snapshot.from_grpc snp_grpc, session
             yield snp if block_given?
           ensure
-            Thread.current[:transaction_id] = nil
+            Thread.current[IS_TRANSACTION_RUNNING_KEY] = nil
           end
           nil
         end
@@ -2272,6 +2273,18 @@ module Google
           nil
         end
 
+        ##
+        # Determines if a transaction error should be propagated to the user.
+        # And re-raises the error accordingly
+        def check_and_propagate_err! err, deadline_passed
+          raise err if internal_error_and_not_retryable? err
+          return unless deadline_passed
+          if err.is_a? GRPC::BadStatus
+            raise Google::Cloud::Error.from_error err
+          end
+          raise err
+        end
+
         def internal_error_and_not_retryable? error
           (error.instance_of?(Google::Cloud::InternalError) ||
           error.instance_of?(GRPC::Internal)) &&

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

@@ -29,19 +29,15 @@ module Google
       # {Google::Cloud::Spanner::Session} instances.
       #
       class Pool
-        attr_accessor :all_sessions
-        attr_accessor :session_stack
-        attr_accessor :transaction_stack
+        attr_accessor :sessions_available
+        attr_accessor :sessions_in_use
 
         def initialize client, min: 10, max: 100, keepalive: 1800,
-                       write_ratio: 0.3, fail: true, threads: nil
+                       fail: true, threads: nil
           @client = client
           @min = min
           @max = max
           @keepalive = keepalive
-          @write_ratio = write_ratio
-          @write_ratio = 0 if write_ratio.negative?
-          @write_ratio = 1 if write_ratio > 1
           @fail = fail
           @threads = threads || [2, Concurrent.processor_count * 2].max
 
@@ -69,10 +65,11 @@ module Google
 
               # Use LIFO to ensure sessions are used from backend caches, which
               # will reduce the read / write latencies on user requests.
-              read_session = session_stack.pop # LIFO
-              return read_session if read_session
-              write_transaction = transaction_stack.pop # LIFO
-              return write_transaction.session if write_transaction
+              read_session = sessions_available.pop # LIFO
+              if read_session
+                sessions_in_use << read_session
+                return read_session
+              end
 
               if can_allocate_more_sessions?
                 action = :new
@@ -85,73 +82,25 @@ module Google
             end
           end
 
-          return new_session! if action == :new
-        end
-
-        def checkin_session session
-          @mutex.synchronize do
-            unless all_sessions.include? session
-              raise ArgumentError, "Cannot checkin session"
+          if action == :new
+            session = new_session!
+            @mutex.synchronize do
+              sessions_in_use << session
             end
-
-            session_stack.push session
-
-            @resource.signal
+            return session
           end
 
           nil
         end
 
-        def with_transaction
-          tx = checkout_transaction
-          begin
-            yield tx
-          ensure
-            future do
-              # Create and checkin a new transaction
-              tx = tx.session.create_transaction
-              checkin_transaction tx
-            end
-          end
-        end
-
-        def checkout_transaction
-          action = nil
-          @mutex.synchronize do
-            loop do
-              raise ClientClosedError if @closed
-
-              write_transaction = transaction_stack.pop # LIFO
-              return write_transaction if write_transaction
-              read_session = session_stack.pop
-              if read_session
-                action = read_session
-                break
-              end
-
-              if can_allocate_more_sessions?
-                action = :new
-                break
-              end
-
-              raise SessionLimitError if @fail
-
-              @resource.wait @mutex
-            end
-          end
-          if action.is_a? Google::Cloud::Spanner::Session
-            return action.create_transaction
-          end
-          return new_transaction! if action == :new
-        end
-
-        def checkin_transaction txn
+        def checkin_session session
           @mutex.synchronize do
-            unless all_sessions.include? txn.session
+            unless sessions_in_use.include? session
               raise ArgumentError, "Cannot checkin session"
             end
 
-            transaction_stack.push txn
+            sessions_available.push session
+            sessions_in_use.delete_if { |s| s.session_id == session.session_id }
 
             @resource.signal
           end
@@ -182,22 +131,20 @@ module Google
           to_release = []
 
           @mutex.synchronize do
-            available_count = session_stack.count + transaction_stack.count
+            available_count = sessions_available.count
             release_count = @min - available_count
             release_count = 0 if release_count.negative?
 
-            to_keepalive += (session_stack + transaction_stack).select do |x|
+            to_keepalive += sessions_available.select do |x|
               x.idle_since? @keepalive
             end
 
-            # Remove a random portion of the sessions and transactions
+            # Remove a random portion of the sessions
             to_release = to_keepalive.sample release_count
             to_keepalive -= to_release
 
             # Remove those to be released from circulation
-            @all_sessions -= to_release.map(&:session)
-            @session_stack -= to_release
-            @transaction_stack -= to_release
+            @sessions_available -= to_release
           end
 
           to_release.each { |x| future { x.release! } }
@@ -212,19 +159,11 @@ module Google
             max_threads: @threads
           # init the stacks
           @new_sessions_in_process = 0
-          @transaction_stack = []
           # init the keepalive task
           create_keepalive_task!
           # init session stack
-          @all_sessions = @client.batch_create_new_sessions @min
-          sessions = @all_sessions.dup
-          num_transactions = (@min * @write_ratio).round
-          pending_transactions = sessions.shift num_transactions
-          # init transaction stack
-          pending_transactions.each do |transaction|
-            future { checkin_transaction transaction.create_transaction }
-          end
-          @session_stack = sessions
+          @sessions_available = @client.batch_create_new_sessions @min
+          @sessions_in_use = []
         end
 
         def shutdown
@@ -236,10 +175,10 @@ module Google
           @resource.broadcast
           # Delete all sessions
           @mutex.synchronize do
-            @all_sessions.each { |s| future { s.release! } }
-            @all_sessions = []
-            @session_stack = []
-            @transaction_stack = []
+            sessions_available.each { |s| future { s.release! } }
+            sessions_in_use.each { |s| future { s.release! } }
+            @sessions_available = []
+            @sessions_in_use = []
           end
           # shutdown existing thread pool
           @thread_pool.shutdown
@@ -261,19 +200,14 @@ module Google
 
           @mutex.synchronize do
             @new_sessions_in_process -= 1
-            all_sessions << session
           end
 
           session
         end
 
-        def new_transaction!
-          new_session!.create_transaction
-        end
-
         def can_allocate_more_sessions?
           # This is expected to be called from within a synchronize block
-          all_sessions.size + @new_sessions_in_process < @max
+          sessions_available.size + sessions_in_use.size + @new_sessions_in_process < @max
         end
 
         def create_keepalive_task!

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

@@ -515,17 +515,14 @@ module Google
         #     before an attempt is made to prevent the idle sessions from being
         #     closed by the Cloud Spanner service. The default is 1800 (30
         #     minutes).
-        #   * `:write_ratio` (Float) The ratio of sessions with pre-allocated
-        #     transactions to those without. Pre-allocating transactions
-        #     improves the performance of writes made by the client. The higher
-        #     the value, the more transactions are pre-allocated. The value must
-        #     be >= 0 and <= 1. The default is 0.3.
         #   * `:fail` (true/false) When `true` the client raises a
         #     {SessionLimitError} when the client has allocated the `max` number
         #     of sessions. When `false` the client blocks until a session
         #     becomes available. The default is `true`.
         #   * `:threads` (Integer) The number of threads in the thread pool. The
         #     default is twice the number of available CPUs.
+        #   * `:write_ratio` (Float) Deprecated. This field is no longer needed
+        #     and will be removed in a future release.
         # @param [Hash] labels The labels to be applied to all sessions
         #   created by the client. Cloud Labels are a flexible and lightweight
         #   mechanism for organizing cloud resources into groups that reflect a
@@ -674,8 +671,7 @@ module Google
         def valid_session_pool_options opts = {}
           {
             min: opts[:min], max: opts[:max], keepalive: opts[:keepalive],
-            write_ratio: opts[:write_ratio], fail: opts[:fail],
-            threads: opts[:threads]
+            fail: opts[:fail], threads: opts[:threads]
           }.compact
         end
       end

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

@@ -41,6 +41,11 @@ module Google
       #   end
       #
       class Results
+        ##
+        # @private Object of type
+        # Google::Cloud::Spanner::V1::ResultSetMetadata
+        attr_reader :metadata
+
         ##
         # The read timestamp chosen for single-use snapshots (read-only
         # transactions).
@@ -73,6 +78,13 @@ module Google
           @fields ||= Fields.from_grpc @metadata.row_type.fields
         end
 
+        ##
+        # @private
+        # Returns a transaction if available
+        def transaction
+          @metadata&.transaction
+        end
+
         # rubocop:disable all
 
         ##
@@ -297,49 +309,20 @@ module Google
         end
 
         # @private
-
-        def self.execute_query service, session_path, sql, params: nil,
-                               types: nil, transaction: nil,
-                               partition_token: nil, seqno: nil,
-                               query_options: nil, request_options: nil,
-                               call_options: nil, data_boost_enabled: nil
-          execute_query_options = {
-            transaction: transaction, params: params, types: types,
-            partition_token: partition_token, seqno: seqno,
-            query_options: query_options, request_options: request_options,
-            call_options: call_options
-          }
-          execute_query_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
-          enum = service.execute_streaming_sql session_path, sql,
-                                               **execute_query_options
-          from_enum(enum, service).tap do |results|
+        def self.from_execute_query_response response, service, session_path, sql, execute_query_options
+          from_enum(response, service).tap do |results|
             results.instance_variable_set :@session_path, session_path
-            results.instance_variable_set :@sql,          sql
-            results.instance_variable_set :@execute_query_options,
-                                          execute_query_options
+            results.instance_variable_set :@sql, sql
+            results.instance_variable_set :@execute_query_options, execute_query_options
           end
         end
 
         # @private
-        def self.read service, session_path, table, columns, keys: nil,
-                      index: nil, limit: nil, transaction: nil,
-                      partition_token: nil, request_options: nil,
-                      call_options: nil, data_boost_enabled: nil
-          read_options = {
-            keys: keys, index: index, limit: limit,
-            transaction: transaction,
-            partition_token: partition_token,
-            request_options: request_options,
-            call_options: call_options,
-            data_boost_enabled: data_boost_enabled
-          }
-          read_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
-          enum = service.streaming_read_table \
-            session_path, table, columns, **read_options
-          from_enum(enum, service).tap do |results|
+        def self.from_read_response response, service, session_path, table, columns, read_options
+          from_enum(response, service).tap do |results|
             results.instance_variable_set :@session_path, session_path
-            results.instance_variable_set :@table,        table
-            results.instance_variable_set :@columns,      columns
+            results.instance_variable_set :@table, table
+            results.instance_variable_set :@columns, columns
             results.instance_variable_set :@read_options, read_options
           end
         end

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

@@ -360,17 +360,7 @@ module Google
             seqno: seqno,
             request_options: request_options
           }
-          results = service.execute_batch_dml request, opts
-
-          if results.status.code.zero?
-            results.result_sets.map { |rs| rs.stats.row_count_exact }
-          else
-            begin
-              raise Google::Cloud::Error.from_error results.status
-            rescue Google::Cloud::Error
-              raise Google::Cloud::Spanner::BatchUpdateError.from_grpc results
-            end
-          end
+          service.execute_batch_dml request, opts
         end
 
         def streaming_read_table session_name, table_name, columns, keys: nil,

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

@@ -345,16 +345,18 @@ module Google
           else
             query_options = @query_options.merge query_options unless @query_options.nil?
           end
-          results = Results.execute_query service, path, sql,
-                                          params: params,
-                                          types: types,
-                                          transaction: transaction,
-                                          partition_token: partition_token,
-                                          seqno: seqno,
-                                          query_options: query_options,
-                                          request_options: request_options,
-                                          call_options: call_options,
-                                          data_boost_enabled: data_boost_enabled
+
+          execute_query_options = {
+            transaction: transaction, params: params, types: types,
+            partition_token: partition_token, seqno: seqno,
+            query_options: query_options, request_options: request_options,
+            call_options: call_options
+          }
+          execute_query_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
+
+          response = service.execute_streaming_sql path, sql, **execute_query_options
+
+          results = Results.from_execute_query_response response, service, path, sql, execute_query_options
           @last_updated_at = Time.now
           results
         end
@@ -500,14 +502,23 @@ module Google
                  call_options: nil, data_boost_enabled: nil
           ensure_service!
 
-          results = Results.read service, path, table, columns,
-                                 keys: keys, index: index, limit: limit,
-                                 transaction: transaction,
-                                 partition_token: partition_token,
-                                 request_options: request_options,
-                                 call_options: call_options,
-                                 data_boost_enabled: data_boost_enabled
+          read_options = {
+            keys: keys, index: index, limit: limit,
+            transaction: transaction,
+            partition_token: partition_token,
+            request_options: request_options,
+            call_options: call_options,
+            data_boost_enabled: data_boost_enabled
+          }
+          read_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
+
+          response = service.streaming_read_table \
+            path, table, columns, **read_options
+
+          results = Results.from_read_response response, service, path, table, columns, read_options
+
           @last_updated_at = Time.now
+
           results
         end
 
@@ -1173,6 +1184,14 @@ module Google
           Transaction.from_grpc tx_grpc, self
         end
 
+        ##
+        # @private
+        # Creates a new transaction object without the grpc object
+        # within it. Use it for inline-begin of a transaction.
+        def create_empty_transaction
+          Transaction.from_grpc nil, self
+        end
+
         ##
         # Reloads the session resource. Useful for determining if the session is
         # still valid on the Spanner API.

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

@@ -17,6 +17,7 @@ require "google/cloud/spanner/errors"
 require "google/cloud/spanner/convert"
 require "google/cloud/spanner/results"
 require "google/cloud/spanner/commit"
+require "google/cloud/spanner/batch_update_results"
 
 module Google
   module Cloud
@@ -74,6 +75,9 @@ module Google
       #   end
       #
       class Transaction
+        # @private The `Google::Cloud::Spanner::V1::Transaction` object.
+        attr_reader :grpc
+
         # @private The Session object.
         attr_accessor :session
 
@@ -83,13 +87,31 @@ module Google
         def initialize
           @commit = Commit.new
           @seqno = 0
+
+          # Mutex to enfore thread safety for transaction creation and query executions.
+          #
+          # This mutex protects two things:
+          # (1) the generation of sequence numbers
+          # (2) the creation of transactions.
+          #
+          # Specifically, @seqno is protected so it always reflects the last sequence number
+          # generated and provided to an operation in any thread. Any acquisition of a
+          # sequence number must be synchronized.
+          #
+          # Furthermore, @grpc is protected such that it either is nil if the
+          # transaction has not yet been created, or references the transaction
+          # resource if the transaction has been created. Any operation that could
+          # create a transaction must be synchronized, and any logic that depends on
+          # the state of transaction creation must also be synchronized.
+          @mutex = Mutex.new
         end
 
         ##
         # Identifier of the transaction results were run in.
         # @return [String] The transaction id.
         def transaction_id
-          return nil if @grpc.nil?
+          return @grpc.id if existing_transaction?
+          safe_begin_transaction
           @grpc.id
         end
 
@@ -337,15 +359,18 @@ module Google
                           request_options: nil, call_options: nil
           ensure_session!
 
-          @seqno += 1
-
           params, types = Convert.to_input_params_and_types params, types
           request_options = build_request_options request_options
-          session.execute_query sql, params: params, types: types,
-                                     transaction: tx_selector, seqno: @seqno,
-                                     query_options: query_options,
-                                     request_options: request_options,
-                                     call_options: call_options
+
+          safe_execute do |seqno|
+            results = session.execute_query sql, params: params, types: types,
+                                            transaction: tx_selector, seqno: seqno,
+                                            query_options: query_options,
+                                            request_options: request_options,
+                                            call_options: call_options
+            @grpc ||= results.transaction
+            results
+          end
         end
         alias execute execute_query
         alias query execute_query
@@ -612,12 +637,24 @@ module Google
         #
         def batch_update request_options: nil, call_options: nil, &block
           ensure_session!
-          @seqno += 1
 
           request_options = build_request_options request_options
-          session.batch_update tx_selector, @seqno,
-                               request_options: request_options,
-                               call_options: call_options, &block
+          safe_execute do |seqno|
+            batch_update_results = nil
+            begin
+              response = session.batch_update tx_selector, seqno,
+                                              request_options: request_options,
+                                              call_options: call_options, &block
+              batch_update_results = BatchUpdateResults.new response
+              row_counts = batch_update_results.row_counts
+              @grpc ||= batch_update_results.transaction
+              return row_counts
+            rescue Google::Cloud::Spanner::BatchUpdateError
+              @grpc ||= batch_update_results.transaction
+              # Re-raise after extracting transaction
+              raise
+            end
+          end
         end
 
         ##
@@ -686,10 +723,15 @@ module Google
           columns = Array(columns).map(&:to_s)
           keys = Convert.to_key_set keys
           request_options = build_request_options request_options
-          session.read table, columns, keys: keys, index: index, limit: limit,
-                                       transaction: tx_selector,
-                                       request_options: request_options,
-                                       call_options: call_options
+
+          safe_execute do
+            results = session.read table, columns, keys: keys, index: index, limit: limit,
+                                   transaction: tx_selector,
+                                   request_options: request_options,
+                                   call_options: call_options
+            @grpc ||= results.transaction
+            results
+          end
         end
 
         ##
@@ -1111,12 +1153,69 @@ module Google
           end
         end
 
+        ##
+        # @private Checks if a transaction is already created.
+        def existing_transaction?
+          !no_existing_transaction?
+        end
+
+        ##
+        # @private Checks if transaction is not already created.
+        def no_existing_transaction?
+          @grpc.nil?
+        end
+
         protected
 
-        # The TransactionSelector to be used for queries
+        ##
+        # @private Facilitates a thread-safe execution of an rpc
+        # for inline-begin of a transaction. This method is optimised to
+        # use mutexes only when necessary, while still acheiving thread-safety.
+        #
+        # Note: Do not use @seqno directly while using this method. Instead, use
+        # the seqno variable passed to the block.
+        def safe_execute
+          loop do
+            if existing_transaction?
+              # Create a local copy of @seqno to avoid concurrent
+              # operations overriding the incremented value.
+              seqno = safe_next_seqno
+              # If a transaction already exists, execute rpc without mutex
+              return yield seqno
+            end
+
+            @mutex.synchronize do
+              next if existing_transaction?
+              @seqno += 1
+              return yield @seqno
+            end
+          end
+        end
+
+        ##
+        # Create a new transaction in a thread-safe manner.
+        def safe_begin_transaction
+          @mutex.synchronize do
+            return if existing_transaction?
+            ensure_session!
+            @grpc = service.begin_transaction session.path
+          end
+        end
+
+        ##
+        # @private The TransactionSelector to be used for queries. This method must
+        #   be called from within a synchronized block, since the value returned
+        #   depends on the state of @grpc field.
+        #
+        #   This method is expected to be called from within `safe_execute()` method's block,
+        #   since it provides synchronization and gurantees thread safety.
         def tx_selector
-          return nil if transaction_id.nil?
-          V1::TransactionSelector.new id: transaction_id
+          return V1::TransactionSelector.new id: transaction_id if existing_transaction?
+          V1::TransactionSelector.new(
+            begin: V1::TransactionOptions.new(
+              read_write: V1::TransactionOptions::ReadWrite.new
+            )
+          )
         end
 
         ##
@@ -1133,6 +1232,15 @@ module Google
           options
         end
 
+        ##
+        # @private Generates the next seqno in a thread-safe manner.
+        def safe_next_seqno
+          @mutex.synchronize do
+            @seqno += 1
+            return @seqno
+          end
+        end
+
         ##
         # @private Raise an error unless an active connection to the service is
         # available.

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.17.0".freeze
+      VERSION = "2.18.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.17.0
+  version: 2.18.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-23 00:00:00.000000000 Z
+date: 2023-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -295,6 +295,7 @@ files:
 - lib/google/cloud/spanner/batch_client.rb
 - lib/google/cloud/spanner/batch_snapshot.rb
 - lib/google/cloud/spanner/batch_update.rb
+- lib/google/cloud/spanner/batch_update_results.rb
 - lib/google/cloud/spanner/client.rb
 - lib/google/cloud/spanner/column_value.rb
 - lib/google/cloud/spanner/commit.rb
@@ -347,7 +348,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.2
+rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Spanner API