google-cloud-spanner 2.28.0 → 2.30.0

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

@@ -0,0 +1,125 @@
+# Copyright 2025 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.
+
+require "concurrent"
+require "google/cloud/spanner/session"
+require "google/cloud/spanner/session_creation_options"
+
+module Google
+  module Cloud
+    module Spanner
+      # Cache for the multiplex `{Google::Cloud::Spanner::Session}` instance.
+      # @private
+      class SessionCache
+        # Time in seconds before this SessionCache will refresh the session.
+        # Counted from the session creation time (not from last usage).
+        # This is specific to multiplex sessions.
+        # The backend can keep sessions alive for quite a bit longer (28 days) but
+        # we perform refresh after 7 days.
+        # @private
+        SESSION_REFRESH_SEC = 7 * 24 * 3600
+
+        # Create a single-session "cache" for multiplex sessions.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @param session_creation_options [::Google::Cloud::Spanner::SessionCreationOptions] Required.
+        # @private
+        def initialize service, session_creation_options
+          @service = service
+          @session_creation_options = session_creation_options
+          @mutex = Mutex.new
+          @session = nil
+        end
+
+        # Yields the current session to run an operation (or a series of operations) on.
+        # @yield session A session to run requests on
+        # @yieldparam session [::Google::Cloud::Spanner::Session]
+        # @private
+        # @yieldreturn [::Object] The result of the operation that ran on a session.
+        # @return [::Object] The value returned by the yielded block.
+        def with_session
+          ensure_session!
+          yield @session
+        end
+
+        # Re-initializes the session in the session cache.
+        # @private
+        # @return [::Boolean]
+        def reset!
+          @mutex.synchronize do
+            @session = create_new_session
+          end
+
+          true
+        end
+
+        # Closes the pool. This is a NOP for Multiplex Session Cache since
+        # multiplex sessions don't require cleanup.
+        # @private
+        # @return [::Boolean]
+        def close
+          true
+        end
+
+        # Returns the current session. For use in the `{Spanner::BatchClient}`
+        # where usage pattern is incompatible with `with_session`.
+        # For other uses please use `with_session` instead.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
+        def session
+          ensure_session!
+          @session
+        end
+
+        private
+
+        # Ensures that a single session exists and is current.
+        # @private
+        # @return [nil]
+        def ensure_session!
+          return unless @session.nil? || @session.existed_since?(SESSION_REFRESH_SEC)
+
+          @mutex.synchronize do
+            return unless @session.nil? || @session.existed_since?(SESSION_REFRESH_SEC)
+            @session = create_new_session
+          end
+
+          nil
+        end
+
+        # Creates a new multiplexed `Spanner::Session`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
+        def create_new_session
+          ensure_service!
+          grpc = @service.create_session(
+            @session_creation_options.database_path,
+            labels:  @session_creation_options.session_labels,
+            database_role: @session_creation_options.session_creator_role,
+            multiplexed: true
+          )
+
+          Session.from_grpc grpc, @service, query_options: @session_creation_options.query_options
+        end
+
+        # Raise an error unless an active connection to the service is available.
+        # @private
+        # @raise [::StandardError]
+        # @return [void]
+        def ensure_service!
+          raise "Must have active connection to service" unless @service
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# Copyright 2025 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
+      # Options for creating new sessions that clients use
+      # to parametrize Pool and SessionCache.
+      # Example: session labels.
+      # @private
+      class SessionCreationOptions
+        # The full path to the Spanner database. Values are of the form:
+        # `projects/<project_id>/instances/<instance_id>/databases/<database_id>.
+        # @private
+        # @return [::String]
+        attr_reader :database_path
+
+        # The labels to be applied to all sessions created by the client.
+        # Optional. Example: `"team" => "billing-service"`.
+        # @private
+        # @return [::Hash, nil]
+        attr_reader :session_labels
+
+        # The Spanner session creator role.
+        # Optional. Example: `analyst`.
+        # @return [::String, nil]
+        attr_reader :session_creator_role
+
+        # A hash of values to specify the custom query options for executing SQL query.
+        # Optional. Example option: `:optimizer_version`.
+        # @private
+        # @return [::Hash, nil]
+        attr_reader :query_options
+
+        # Creates a new SessionCreationOptions object.
+        # @param database_path [::String]
+        #   The full path to the Spanner database. Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param session_creator_role [::String, nil] Optional. The Spanner session creator role.
+        #   Example: `analyst`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example option: `:optimizer_version`.
+        # @private
+        def initialize database_path:, session_labels: nil, session_creator_role: nil, query_options: nil
+          if database_path.nil? || database_path.empty?
+            raise ArgumentError, "database_path is required for session creation options"
+          end
+
+          @database_path = database_path
+          @session_labels = session_labels
+          @session_creator_role = session_creator_role
+          @query_options = query_options
+        end
+      end
+    end
+  end
+end

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

@@ -41,9 +41,26 @@ module Google
       #   end
       #
       class Snapshot
-        # @private The Session object.
+        # A `V1::Session` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::Session]
         attr_accessor :session
 
+        # Creates a new `Spanner::Snapshot` instance.
+        # @param grpc [::Google::Cloud::Spanner::V1::Transaction]
+        #   Underlying `V1::Transaction` object.
+        # @param session [::Google::Cloud::Spanner::Session] A `Spanner::Session` reference.
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Snapshot]
+        def initialize grpc, session, directed_read_options: nil
+          @grpc = grpc
+          @session = session
+          @directed_read_options = directed_read_options
+        end
+
         ##
         # Identifier of the transaction results were run in.
         # @return [String] The transaction id.
@@ -131,6 +148,18 @@ module Google
         #     available optimizer version.
         #   * `:optimizer_statistics_package` (String) Statistics package to
         #     use. Empty to use the database default.
+        # @param [Hash] request_options Common request options.
+        #
+        #   * `:priority` (Symbol) The relative priority for requests.
+        #     The priority acts as a hint to the Cloud Spanner scheduler
+        #     and does not guarantee priority or order of execution.
+        #     Valid values are `:PRIORITY_LOW`, `:PRIORITY_MEDIUM`,
+        #     `:PRIORITY_HIGH`. If priority not set then default is
+        #     `PRIORITY_UNSPECIFIED` is equivalent to `:PRIORITY_HIGH`.
+        #   * `:tag` (String) A per-request tag which can be applied to
+        #     queries or reads, used for statistics collection. Tag must be a
+        #     valid identifier of the form: `[a-zA-Z][a-zA-Z0-9_\-]` between 2
+        #     and 64 characters in length.
         # @param [Hash] call_options A hash of values to specify the custom
         #   call options, e.g., timeout, retries, etc. Call options are
         #   optional. The following settings can be provided:
@@ -304,13 +333,17 @@ module Google
         #   end
         #
         def execute_query sql, params: nil, types: nil, query_options: nil,
-                          call_options: nil, directed_read_options: nil
+                          request_options: nil, call_options: nil,
+                          directed_read_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
+          request_options = Convert.to_request_options request_options,
+                                                       tag_type: :request_tag
           session.execute_query sql, params: params, types: types,
                                      transaction: tx_selector,
                                      query_options: query_options,
+                                     request_options: request_options,
                                      call_options: call_options,
                                      directed_read_options: directed_read_options || @directed_read_options
         end
@@ -334,6 +367,18 @@ module Google
         #   Optional.
         # @param [Integer] limit If greater than zero, no more than this number
         #   of rows will be returned. The default is no limit.
+        # @param [Hash] request_options Common request options.
+        #
+        #   * `:priority` (Symbol) The relative priority for requests.
+        #     The priority acts as a hint to the Cloud Spanner scheduler
+        #     and does not guarantee priority or order of execution.
+        #     Valid values are `:PRIORITY_LOW`, `:PRIORITY_MEDIUM`,
+        #     `:PRIORITY_HIGH`. If priority not set then default is
+        #     `PRIORITY_UNSPECIFIED` is equivalent to `:PRIORITY_HIGH`.
+        #   * `:tag` (String) A per-request tag which can be applied to
+        #     queries or reads, used for statistics collection. Tag must be a
+        #     valid identifier of the form: `[a-zA-Z][a-zA-Z0-9_\-]` between 2
+        #     and 64 characters in length.
         # @param [Hash] call_options A hash of values to specify the custom
         #   call options, e.g., timeout, retries, etc. Call options are
         #   optional. The following settings can be provided:
@@ -380,7 +425,7 @@ module Google
         #   end
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
-                 call_options: nil, directed_read_options: nil
+                 request_options: nil, call_options: nil, directed_read_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -388,6 +433,7 @@ module Google
 
           session.read table, columns, keys: keys, index: index, limit: limit,
                                        transaction: tx_selector,
+                                       request_options: request_options,
                                        call_options: call_options,
                                        directed_read_options: directed_read_options || @directed_read_options
         end
@@ -507,15 +553,18 @@ module Google
                     exclude_end: exclude_end
         end
 
-        ##
-        # @private Creates a new Snapshot instance from a
+        # Creates a new `Spanner::Snapshot` instance from a
         # `Google::Cloud::Spanner::V1::Transaction`.
-        def self.from_grpc grpc, session, directed_read_options
-          new.tap do |s|
-            s.instance_variable_set :@grpc,    grpc
-            s.instance_variable_set :@session, session
-            s.instance_variable_set :@directed_read_options, directed_read_options
-          end
+        # @param grpc [::Google::Cloud::Spanner::V1::Transaction]
+        #   Underlying `V1::Transaction` object.
+        # @param session [::Google::Cloud::Spanner::Session] A `Spanner::Session` reference.
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Snapshot]
+        def self.from_grpc grpc, session, directed_read_options: nil
+          new grpc, session, directed_read_options: directed_read_options
         end
 
         protected

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.28.0".freeze
+      VERSION = "2.30.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.28.0
+  version: 2.30.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