google-cloud-spanner 2.16.1 → 2.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb26c1ee1cc71cf984fecb01463a35384ee50e68cafd41399c064cc810a298f8
-  data.tar.gz: 5d663434c4a3766acf13c3a03ef851cb81ec839a83bfd4e83340b9b5b22231f4
+  metadata.gz: 37f9332aedaf9d53b1eb13596dafa4b3571393449b85ce5e63750b5c57381e3f
+  data.tar.gz: b137394c7819e4795a98727e626772ece2404ef40bc7ef84153014768ddbfb89
 SHA512:
-  metadata.gz: f8638c29b54887f38252cc916f077d4ea5776602d331c0da853215e80b62b06fe176d6a3972b339cb650a3e936c78bab2ea2776fb0f12cc4911fd57f4c1ae33d
-  data.tar.gz: 7bd143477dbc7b67dde5f9a9cd2a6ae6b77a5b9079117bcae3cbf3006321a3476468d79889c7bb0ffe8cca6c9de4674c7d36f8bc878430bdf6934c2b6064f645
+  metadata.gz: 0ea41265627415904e066549390d59ad72a2be577c3b6f7ac67d8a47197e4f2df4a79f9c2c14735bcd383989b2f3bfa602fe68e3ebde1d7cc055252d8644f36f
+  data.tar.gz: 2cc9bf3bbe521e85c72ad2dd255eedf09225c0bbcc67bc4c319a4036aa7beac01c18f73a0fb6ff1fd203b96b15ff2b3bcbb82f2f8ddfd0f2aa72e1d2f31f03e9

data/AUTHENTICATION.md

@@ -32,7 +32,7 @@ client = Google::Cloud::Spanner.new
 ## Project and Credential Lookup
 
 The google-cloud-spanner library aims to make authentication
-as simple as possible, and provides several mechanisms to configure your system
+as simple as possible and provides several mechanisms to configure your system
 without providing **Project ID** and **Service Account Credentials** directly in
 code.
 

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+* support data_boost_enabled for partitioned query and read ([#46](https://github.com/googleapis/ruby-spanner/issues/46)) 
+
 ### 2.16.1 (2022-11-02)
 
 #### Documentation

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

@@ -188,6 +188,9 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Boolean] data_boost_enabled  If this field is
+        #   set `true`, the request will be executed via offline access.
+        #   Defaults to `false`.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the query partition.
@@ -211,7 +214,7 @@ module Google
         #
         def partition_query sql, params: nil, types: nil,
                             partition_size_bytes: nil, max_partitions: nil,
-                            query_options: nil, call_options: nil
+                            query_options: nil, call_options: nil, data_boost_enabled: false
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
@@ -231,8 +234,9 @@ module Google
                 param_types: types,
                 transaction: tx_selector,
                 partition_token: grpc.partition_token,
-                query_options: query_options
-              }.delete_if { |_, v| v.nil? }
+                query_options: query_options,
+                data_boost_enabled: data_boost_enabled
+              }.compact
             )
             Partition.from_execute_sql_grpc execute_sql_grpc
           end
@@ -277,6 +281,9 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Boolean] data_boost_enabled  If this field is
+        #   set `true`, the request will be executed via offline access.
+        #   Defaults to `false`.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the read partition.
@@ -298,7 +305,7 @@ module Google
         #
         def partition_read table, columns, keys: nil, index: nil,
                            partition_size_bytes: nil, max_partitions: nil,
-                           call_options: nil
+                           call_options: nil, data_boost_enabled: false
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -321,8 +328,9 @@ module Google
                 key_set: keys,
                 index: index,
                 transaction: tx_selector,
-                partition_token: grpc.partition_token
-              }.delete_if { |_, v| v.nil? }
+                partition_token: grpc.partition_token,
+                data_boost_enabled: data_boost_enabled
+              }.compact
             )
             Partition.from_read_grpc read_grpc
           end
@@ -804,7 +812,8 @@ module Google
             transaction: partition.execute.transaction,
             partition_token: partition.execute.partition_token,
             query_options: query_options,
-            call_options: call_options
+            call_options: call_options,
+            data_boost_enabled: partition.execute.data_boost_enabled
         end
 
         def execute_partition_read partition, call_options: nil
@@ -814,7 +823,8 @@ module Google
                        index: partition.read.index,
                        transaction: partition.read.transaction,
                        partition_token: partition.read.partition_token,
-                       call_options: call_options
+                       call_options: call_options,
+                       data_boost_enabled: partition.read.data_boost_enabled
         end
       end
     end

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,44 +1804,44 @@ 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
               resp = CommitResponse.from_grpc commit_resp
               commit_options ? resp : resp.timestamp
-            rescue GRPC::Aborted, Google::Cloud::AbortedError => 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
+            rescue GRPC::Aborted,
+                   Google::Cloud::AbortedError,
+                   GRPC::Internal,
+                   Google::Cloud::InternalError => e
+              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
@@ -1919,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
 
@@ -1929,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
@@ -2215,7 +2220,7 @@ module Google
                 min_read_timestamp: bounded_timestamp,
                 max_staleness: bounded_staleness,
                 return_read_timestamp: true
-              }.delete_if { |_, v| v.nil? })))
+              }.compact)))
         end
 
         def pdml_transaction session
@@ -2267,6 +2272,24 @@ module Google
           # Any error indicates the backoff should be handled elsewhere
           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)) &&
+            !@project.service.retryable?(error)
+        end
       end
     end
   end

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

@@ -94,7 +94,7 @@ module Google
         def upsert table, *rows
           rows = Array(rows).flatten
           return rows if rows.empty?
-          rows.delete_if(&:nil?)
+          rows.compact
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
             V1::Mutation.new(
@@ -153,7 +153,7 @@ module Google
         def insert table, *rows
           rows = Array(rows).flatten
           return rows if rows.empty?
-          rows.delete_if(&:nil?)
+          rows.compact
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
             V1::Mutation.new(
@@ -211,7 +211,7 @@ module Google
         def update table, *rows
           rows = Array(rows).flatten
           return rows if rows.empty?
-          rows.delete_if(&:nil?)
+          rows.compact
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
             V1::Mutation.new(
@@ -271,7 +271,7 @@ module Google
         def replace table, *rows
           rows = Array(rows).flatten
           return rows if rows.empty?
-          rows.delete_if(&:nil?)
+          rows.compact
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
             V1::Mutation.new(

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

@@ -29,26 +29,22 @@ module Google
       # {Google::Cloud::Spanner::Session} instances.
       #
       class Pool
-        attr_accessor :all_sessions
-        attr_accessor :session_queue
-        attr_accessor :transaction_queue
+        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
 
           @mutex = Mutex.new
           @resource = ConditionVariable.new
 
-          # initialize pool and availability queue
+          # initialize pool and availability stack
           init
         end
 
@@ -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_queue.pop # LIFO
-              return read_session if read_session
-              write_transaction = transaction_queue.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_queue.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_queue.pop # LIFO
-              return write_transaction if write_transaction
-              read_session = session_queue.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_queue.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_queue.count + transaction_queue.count
+            available_count = sessions_available.count
             release_count = @min - available_count
             release_count = 0 if release_count.negative?
 
-            to_keepalive += (session_queue + transaction_queue).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_queue -= to_release
-            @transaction_queue -= to_release
+            @sessions_available -= to_release
           end
 
           to_release.each { |x| future { x.release! } }
@@ -210,21 +157,13 @@ module Google
           # init the thread pool
           @thread_pool = Concurrent::ThreadPoolExecutor.new \
             max_threads: @threads
-          # init the queues
+          # init the stacks
           @new_sessions_in_process = 0
-          @transaction_queue = []
           # init the keepalive task
           create_keepalive_task!
-          # init session queue
-          @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 queue
-          pending_transactions.each do |transaction|
-            future { checkin_transaction transaction.create_transaction }
-          end
-          @session_queue = sessions
+          # init session stack
+          @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_queue = []
-            @transaction_queue = []
+            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,9 +671,8 @@ 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]
-          }.delete_if { |_k, v| v.nil? }
+            fail: opts[:fail], threads: opts[:threads]
+          }.compact
         end
       end
     end

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

@@ -41,8 +41,11 @@ module Google
       #   end
       #
       class Results
-        RST_STREAM_INTERNAL_ERROR = "Received RST_STREAM".freeze
-        EOS_INTERNAL_ERROR = "Received unexpected EOS on DATA frame from server".freeze
+        ##
+        # @private Object of type
+        # Google::Cloud::Spanner::V1::ResultSetMetadata
+        attr_reader :metadata
+
         ##
         # The read timestamp chosen for single-use snapshots (read-only
         # transactions).
@@ -75,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
 
         ##
@@ -177,7 +187,7 @@ module Google
 
               if resumable?(resume_token)
                 should_resume_request = true
-              elsif retryable?(err)
+              elsif @service.retryable?(err)
                 should_retry_request = true
               elsif err.is_a?(Google::Cloud::Error)
                 raise err
@@ -227,22 +237,6 @@ module Google
           resume_token && !resume_token.empty?
         end
 
-        ##
-        # @private
-        # Checks if a request can be retried. This is based on the error returned.
-        # Retryable errors are:
-        #   - Unavailable error
-        #   - Internal EOS error
-        #   - Internal RST_STREAM error
-        def retryable? err
-          err.instance_of?(Google::Cloud::UnavailableError) ||
-            err.instance_of?(GRPC::Unavailable) ||
-            (err.instance_of?(Google::Cloud::InternalError) && err.message.include?(EOS_INTERNAL_ERROR)) ||
-            (err.instance_of?(GRPC::Internal) && err.details.include?(EOS_INTERNAL_ERROR)) ||
-            (err.instance_of?(Google::Cloud::InternalError) && err.message.include?(RST_STREAM_INTERNAL_ERROR)) ||
-            (err.instance_of?(GRPC::Internal) && err.details.include?(RST_STREAM_INTERNAL_ERROR))
-        end
-
         ##
         # @private
         # Resumes a request, by re-executing it with a resume token.
@@ -315,46 +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
-          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
-          }
-          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
-          read_options = {
-            keys: keys, index: index, limit: limit,
-            transaction: transaction,
-            partition_token: partition_token,
-            request_options: request_options,
-            call_options: call_options
-          }
-          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

@@ -36,6 +36,9 @@ module Google
         attr_accessor :lib_version
         attr_accessor :quota_project
 
+        RST_STREAM_INTERNAL_ERROR = "Received RST_STREAM".freeze
+        EOS_INTERNAL_ERROR = "Received unexpected EOS on DATA frame from server".freeze
+
         ##
         # Creates a new Service instance.
         def initialize project, credentials, quota_project: nil,
@@ -141,7 +144,7 @@ module Google
             display_name: name, config: instance_config_path(config),
             node_count: nodes, processing_units: processing_units,
             labels: labels
-          }.delete_if { |_, v| v.nil? })
+          }.compact)
 
           request = {
             parent:      project_path,
@@ -326,7 +329,7 @@ module Google
                                   params: nil, types: nil, resume_token: nil,
                                   partition_token: nil, seqno: nil,
                                   query_options: nil, request_options: nil,
-                                  call_options: nil
+                                  call_options: nil, data_boost_enabled: nil
           opts = default_options session_name: session_name,
                                  call_options: call_options
           request =  {
@@ -341,6 +344,7 @@ module Google
             query_options: query_options,
             request_options: request_options
           }
+          request[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
           service.execute_streaming_sql request, opts
         end
 
@@ -356,23 +360,14 @@ 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,
                                  index: nil, transaction: nil, limit: nil,
                                  resume_token: nil, partition_token: nil,
-                                 request_options: nil, call_options: nil
+                                 request_options: nil, call_options: nil,
+                                 data_boost_enabled: nil
           opts = default_options session_name: session_name,
                                  call_options: call_options
           request = {
@@ -381,6 +376,7 @@ module Google
             limit: limit, resume_token: resume_token,
             partition_token: partition_token, request_options: request_options
           }
+          request[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
           service.streaming_read request, opts
         end
 
@@ -470,7 +466,7 @@ module Google
                 read_timestamp: Convert.time_to_timestamp(timestamp),
                 exact_staleness: Convert.number_to_duration(staleness),
                 return_read_timestamp: true
-              }.delete_if { |_, v| v.nil? }
+              }.compact
             )
           )
           opts = default_options session_name: session_name,
@@ -580,6 +576,21 @@ module Google
           databases.restore_database request, opts
         end
 
+        ##
+        # Checks if a request can be retried. This is based on the error returned.
+        # Retryable errors are:
+        #   - Unavailable error
+        #   - Internal EOS error
+        #   - Internal RST_STREAM error
+        def retryable? err
+          err.instance_of?(Google::Cloud::UnavailableError) ||
+            err.instance_of?(GRPC::Unavailable) ||
+            (err.instance_of?(Google::Cloud::InternalError) && err.message.include?(EOS_INTERNAL_ERROR)) ||
+            (err.instance_of?(GRPC::Internal) && err.details.include?(EOS_INTERNAL_ERROR)) ||
+            (err.instance_of?(Google::Cloud::InternalError) && err.message.include?(RST_STREAM_INTERNAL_ERROR)) ||
+            (err.instance_of?(GRPC::Internal) && err.details.include?(RST_STREAM_INTERNAL_ERROR))
+        end
+
         def inspect
           "#{self.class}(#{@project})"
         end

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

@@ -338,22 +338,25 @@ module Google
         #
         def execute_query sql, params: nil, types: nil, transaction: nil,
                           partition_token: nil, seqno: nil, query_options: nil,
-                          request_options: nil, call_options: nil
+                          request_options: nil, call_options: nil, data_boost_enabled: nil
           ensure_service!
           if query_options.nil?
             query_options = @query_options
           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
+
+          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
@@ -496,16 +499,26 @@ module Google
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
                  transaction: nil, partition_token: nil, request_options: nil,
-                 call_options: nil
+                 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
+          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
 
@@ -1171,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.16.1".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.16.1
+  version: 2.18.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-02 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.3.14
+rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Spanner API