google-cloud-spanner 2.29.0 → 2.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c47f3cfa10a6d612de5578cd6602dece290f316246a809a265b504fc74737307
-  data.tar.gz: fe95585faa6210cb5110dbc54e3bb95e0a9126577c1893854880ebd8232946a1
+  metadata.gz: '0048ff04c4a29b66a58595d58a68c5be48f765d5aa8e0f6fd5c27b0ca7b1c088'
+  data.tar.gz: 195570ee1bc8eb9b7c33d525df148aaa1a230693ae237b82f30d7e573866c3df
 SHA512:
-  metadata.gz: fa836a8f8a9e7da61b9ca53e655a8ab0870dcc50435756af6d2637931b9f16c1f12853a4eab16038176ca4b85395f6d83d7cbccec9a8c37ad5c562f9ee83ad2e
-  data.tar.gz: 873894c371f0f7e9679a4df3f4b8fdc28e0047f135584b11616bc25f53982ef42b378cd323c3216d2283f6517071d218dc8a1c7a60fb1b842bac9422fa0b3bda
+  metadata.gz: 37b100e79176dfc4fa89f80832ae04f81b7f8d027704bed6e0dcf217708fcbf7be3a2632961f55eda21fd0a4de7804eb2bd6b47172fa9901039d71d9018db99d
+  data.tar.gz: 5b308e03caf25c9b91ebb4c6433cb29a9eb4e3fe2c3fedbb81f624dc88a02858564ef2e1202ec4aca01021825db99a2fcf756ef978d6d18d23012428b568fa6b

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 2.30.0 (2025-11-17)
+
+#### Features
+
+* implement support for Multiplexed Sessions ([#195](https://github.com/googleapis/ruby-spanner/issues/195)) 
+
 ### 2.29.0 (2025-11-06)
 
 #### Features

data/lib/google/cloud/spanner/backup/job.rb

@@ -71,7 +71,9 @@ module Google
           ##
           # @private Creates a new Backup::Job instance.
           def initialize
+            # @type [::Gapic::Operation, nil]
             @grpc = nil
+            # @type [::Google::Cloud::Spanner::Service, nil]
             @service = nil
           end
 
@@ -268,7 +270,7 @@ module Google
           end
 
           # Create a new Backup::Job from a `Gapic::Operation` object.
-          # @param grpc [::Gapic::Operation`] The wrapped `Gapic::Operation` object.
+          # @param grpc [::Gapic::Operation`] Underlying `Gapic::Operation` object.
           # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
           # @private
           # @return [::Google::Cloud::Spanner::Backup::Job]

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

@@ -16,6 +16,8 @@
 require "google/cloud/spanner/errors"
 require "google/cloud/spanner/project"
 require "google/cloud/spanner/session"
+require "google/cloud/spanner/session_cache"
+require "google/cloud/spanner/session_creation_options"
 require "google/cloud/spanner/batch_snapshot"
 
 module Google
@@ -83,6 +85,16 @@ module Google
           @session_labels = session_labels
           @query_options = query_options
           @directed_read_options = directed_read_options
+
+          session_creation_options = SessionCreationOptions.new(
+            database_path:  Admin::Database::V1::DatabaseAdmin::Paths.database_path(
+              project: @project.service.project, instance: instance_id, database: database_id
+            ),
+            session_labels: @session_labels,
+            query_options: @query_options
+          )
+
+          @session_cache = SessionCache.new @project.service, session_creation_options
         end
 
         # The unique identifier for the project.
@@ -110,13 +122,15 @@ module Google
         end
 
         # The Spanner instance connected to.
-        # @return [Instance]
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Instance#instance_admin} instead.
+        # @return [::Google::Cloud::Spanner::Instance]
         def instance
           @project.instance instance_id
         end
 
         # The Spanner database connected to.
-        # @return [Database]
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Database#database_admin} instead.
+        # @return [::Google::Cloud::Spanner::Database]
         def database
           @project.database instance_id, database_id
         end
@@ -428,12 +442,7 @@ module Google
         # @return [::Google::Cloud::Spanner::Session]
         def session
           ensure_service!
-          grpc = @project.service.create_session \
-            V1::Spanner::Paths.database_path(
-              project: project_id, instance: instance_id, database: database_id
-            ),
-            labels: @session_labels
-          Session.from_grpc grpc, @project.service, query_options: @query_options
+          @session_cache.session
         end
 
         ##

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

@@ -68,8 +68,15 @@ module Google
         # @private Directed Read Options
         attr_reader :directed_read_options
 
-        ##
-        # @private Creates a BatchSnapshot object.
+        # Creates a new `Spanner::BatchSnapshot` 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::BatchSnapshot]
         def initialize grpc, session, directed_read_options: nil
           @grpc = grpc
           @session = session
@@ -852,9 +859,16 @@ module Google
           from_grpc transaction_grpc, Session.from_grpc(session_grpc, service, query_options: query_options)
         end
 
-        ##
-        # @private Creates a new BatchSnapshot instance from a
+        # Creates a new BatchSnapshot instance from a
         # `Google::Cloud::Spanner::V1::Transaction`.
+        # @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::BatchSnapshot]
         def self.from_grpc grpc, session, directed_read_options: nil
           new grpc, session, directed_read_options: directed_read_options
         end

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

@@ -19,10 +19,15 @@ module Google
       ##
       # @private Helper class to process BatchDML response
       class BatchUpdateResults
-        ## Object of type
-        # Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse
+        # The `V1::ExecuteBatchDmlResponse` object to process
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse]
         attr_reader :grpc
 
+        # Initializes the `BatchUpdateResults` helper
+        # @private
+        # @param grpc [::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse]
+        #   The response from `ExecuteBatchDml` rpc to process in this helper.
         def initialize grpc
           @grpc = grpc
         end

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

@@ -16,7 +16,8 @@
 require "google/cloud/spanner/errors"
 require "google/cloud/spanner/project"
 require "google/cloud/spanner/data"
-require "google/cloud/spanner/pool"
+require "google/cloud/spanner/session_cache"
+require "google/cloud/spanner/session_creation_options"
 require "google/cloud/spanner/session"
 require "google/cloud/spanner/transaction"
 require "google/cloud/spanner/snapshot"
@@ -61,8 +62,9 @@ module Google
         # @param database_id [::String] Database id, e.g. `"my-database"`.
         # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
         #   created by the client. Example: `"team" => "billing-service"`.
-        # @param pool_opts [::Hash] Optional. `Spanner::Pool` creation options.
-        #   Example parameter: `:keepalive`.
+        # @param pool_opts [::Hash] Optional. Defaults to `{}`. Deprecated.
+        #   @deprecated This parameter is non-functional since the multiplexed SessionCache does not require
+        #   pool options.
         # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
         #   query options for executing SQL query. Example parameter `:optimizer_version`.
         # @param database_role [::String, nil] Optional. The Spanner session creator role.
@@ -79,9 +81,21 @@ module Google
           @database_id = database_id
           @database_role = database_role
           @session_labels = session_labels
-          @directed_read_options = directed_read_options
-          @pool = Pool.new self, **pool_opts
           @query_options = query_options
+          @directed_read_options = directed_read_options
+
+          _pool_opts = pool_opts # unused. Here only to avoid having to disable Rubocop's Lint/UnusedMethodArgument
+
+          session_creation_options = SessionCreationOptions.new(
+            database_path:  Admin::Database::V1::DatabaseAdmin::Paths.database_path(
+              project: @project.service.project, instance: instance_id, database: database_id
+            ),
+            session_labels: @session_labels,
+            session_creator_role: @database_role,
+            query_options: @query_options
+          )
+
+          @pool = SessionCache.new @project.service, session_creation_options
         end
 
         # The unique identifier for the project.
@@ -1943,7 +1957,8 @@ module Google
         # rubocop:disable Metrics/AbcSize
         # rubocop:disable Metrics/MethodLength
         # rubocop:disable Metrics/BlockLength
-
+        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable Metrics/PerceivedComplexity
 
         ##
         # Creates a transaction for reads and writes that execute atomically at
@@ -2128,9 +2143,10 @@ module Google
               yield tx
 
               unless tx.existing_transaction?
-                # This can happen if the yielded `tx` object was only used to add mutations.
+                # This typically will happen if the yielded `tx` object was only used to add mutations.
                 # Then it never called any RPCs and didn't create a server-side Transaction object.
                 # In which case we should make an explicit BeginTransaction call here.
+
                 tx.safe_begin_transaction!(
                   exclude_from_change_streams: exclude_txn_from_change_streams,
                   request_options: request_options,
@@ -2139,15 +2155,28 @@ module Google
               end
 
               transaction_id = tx.transaction_id
-              commit_resp = @project.service.commit(
-                tx.session.path,
-                tx.mutations,
-                transaction_id: transaction_id,
-                exclude_txn_from_change_streams: exclude_txn_from_change_streams,
-                commit_options: commit_options,
-                request_options: request_options,
-                call_options: call_options
-              )
+
+              # This "inner retry" mechanism is for Commit Response protocol.
+              # Unlike the retry on `Aborted` errors it will not re-create a transaction.
+              # This is intentional, as these retries are not related to e.g.
+              # transactions deadlocking, so it's OK to retry "as-is".
+              should_retry = true
+              while should_retry
+                commit_resp = @project.service.commit(
+                  tx.session.path,
+                  tx.mutations,
+                  transaction_id: transaction_id,
+                  exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                  commit_options: commit_options,
+                  request_options: request_options,
+                  call_options: call_options,
+                  precommit_token: tx.precommit_token
+                )
+
+                tx.precommit_token = commit_resp.precommit_token
+                should_retry = !commit_resp.precommit_token.nil?
+              end
+
               resp = CommitResponse.from_grpc commit_resp
               commit_options ? resp : resp.timestamp
             rescue GRPC::Aborted,
@@ -2157,8 +2186,16 @@ module Google
               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 = session.create_transaction exclude_txn_from_change_streams: exclude_txn_from_change_streams
+              previous_transaction_id = tx.transaction_id if tx.existing_transaction?
+              tx = session.create_empty_transaction(
+                exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                previous_transaction_id: previous_transaction_id
+              )
+              if request_options
+                tx.transaction_tag = request_options[:transaction_tag]
+              end
               retry
             rescue StandardError => e
               # Rollback transaction when handling unexpected error
@@ -2176,6 +2213,9 @@ module Google
         # rubocop:enable Metrics/AbcSize
         # rubocop:enable Metrics/MethodLength
         # rubocop:enable Metrics/BlockLength
+        # rubocop:enable Metrics/CyclomaticComplexity
+        # rubocop:enable Metrics/PerceivedComplexity
+
 
         ##
         # Creates a snapshot read-only transaction for reads that execute
@@ -2262,7 +2302,7 @@ module Google
                             staleness: staleness || exact_staleness,
                             call_options: call_options
             Thread.current[IS_TRANSACTION_RUNNING_KEY] = true
-            snp = Snapshot.from_grpc snp_grpc, session, @directed_read_options
+            snp = Snapshot.from_grpc snp_grpc, session, directed_read_options: @directed_read_options
             yield snp if block_given?
           ensure
             Thread.current[IS_TRANSACTION_RUNNING_KEY] = nil
@@ -2442,58 +2482,8 @@ module Google
         ##
         # Reset the client sessions.
         #
-        def reset
-          @pool.reset
-        end
-
-        # Creates a new Session objece.
-        # @param multiplexed [::Boolean] Optional. Default to `false`.
-        #   If `true`, specifies a multiplexed session.
-        # @private
-        # @return [::Google::Cloud::Spanner::Session]
-        def create_new_session multiplexed: false
-          ensure_service!
-          grpc = @project.service.create_session \
-            Admin::Database::V1::DatabaseAdmin::Paths.database_path(
-              project: project_id, instance: instance_id, database: database_id
-            ),
-            labels: @session_labels,
-            database_role: @database_role,
-            multiplexed: multiplexed
-
-          Session.from_grpc grpc, @project.service, query_options: @query_options
-        end
-
-        ##
-        # @private
-        # Creates a batch of new session objects of size `total`.
-        # Makes multiple RPCs if necessary. Returns empty array if total is 0.
-        def batch_create_new_sessions total
-          sessions = []
-          remaining = total
-          while remaining.positive?
-            sessions += batch_create_sessions remaining
-            remaining = total - sessions.count
-          end
-          sessions
-        end
-
-        ##
-        # @private
-        # The response may have fewer sessions than requested in the RPC.
-        #
-        def batch_create_sessions session_count
-          ensure_service!
-          resp = @project.service.batch_create_sessions \
-            Admin::Database::V1::DatabaseAdmin::Paths.database_path(
-              project: project_id, instance: instance_id, database: database_id
-            ),
-            session_count,
-            labels: @session_labels,
-            database_role: @database_role
-          resp.session.map do |grpc|
-            Session.from_grpc grpc, @project.service, query_options: @query_options
-          end
+        def reset!
+          @pool.reset!
         end
 
         # @private
@@ -2516,23 +2506,51 @@ module Google
           raise "Must have active connection to service" unless @project.service
         end
 
-        ##
-        # Check for valid snapshot arguments
+        # Checks that the options hash contains exactly one valid single-use key.
+        #
+        # @param opts [::Hash, nil] The options hash to validate.
+        # @private
+        # @raise [ArgumentError] If the hash does not contain exactly one valid
+        #   single-use key.
+        # @return [void]
         def validate_single_use_args! opts
-          return true if opts.nil? || opts.empty?
-          valid_keys = %i[strong timestamp read_timestamp staleness
-                          exact_staleness bounded_timestamp
-                          min_read_timestamp bounded_staleness max_staleness]
-          if opts.keys.count == 1 && valid_keys.include?(opts.keys.first)
-            return true
-          end
+          # An empty options hash is valid.
+          return if opts.nil? || opts.empty?
+
+          keys = opts.keys
+
+          valid_keys = Set.new(%i[
+                                 strong timestamp read_timestamp staleness exact_staleness
+                                 bounded_timestamp min_read_timestamp bounded_staleness max_staleness
+                               ]).freeze
+
+          # Raise an error unless there is exactly one key and it's in the valid set.
+          return if keys.length == 1 && valid_keys.include?(keys.first)
           raise ArgumentError,
-                "Must provide only one of the following single_use values: " \
-                "#{valid_keys}"
+                "Options must contain exactly one of the following keys: " \
+                "#{valid_keys.to_a.join ', '}"
         end
 
-        ##
-        # Create a single-use TransactionSelector
+        # Creates a selector for a single-use, read-only transaction.
+        #
+        # @param opts [::Hash] Options for creating the transaction selector.
+        #   If those are `nil` or empty, a `nil` will be returned instead of a `V1::TransactionSelector`.
+        # @option opts [::Boolean] :strong
+        #   Executes a strong read.
+        # @option opts [::Time, ::DateTime] :read_timestamp
+        #   Executes a read at the provided time. Alias: `:timestamp`.
+        # @option opts [::Numeric] :exact_staleness
+        #   Executes a read at a time that is exactly this stale (in seconds).
+        #   Alias: `:staleness`.
+        # @option opts [::Time, ::DateTime] :min_read_timestamp
+        #   Executes a read at a time that is at least this timestamp.
+        #   Alias: `:bounded_timestamp`.
+        # @option opts [::Numeric] :max_staleness
+        #   Executes a read at a time that is at most this stale (in seconds).
+        #   Alias: `:bounded_staleness`.
+        # @private
+        # @return [V1::TransactionSelector, nil] The transaction selector object, or
+        #   `nil` if the `opts` hash is nil or empty.
         def single_use_transaction opts
           return nil if opts.nil? || opts.empty?
 

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

@@ -45,6 +45,7 @@ module Google
         ##
         # @private
         def initialize
+          # @type [Array<Google::Cloud::Spanner::V1::Mutation>]
           @mutations = []
         end
 
@@ -279,7 +280,9 @@ module Google
           keys
         end
 
+        # Return the current mutations added to this `Spanner::Commit` object.
         # @private
+        # @return [Array<Google::Cloud::Spanner::V1::Mutation>]
         def mutations
           @mutations
         end

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

@@ -53,8 +53,11 @@ module Google
       #   puts commit_resp.stats.mutation_count
       #
       class CommitResponse
-        ##
-        # @private Creates a new CommitResponse instance.
+        # Creates a new CommitResponse instance.
+        #
+        # @param grpc [::Google::Cloud::Spanner::V1::CommitResponse]
+        #   Underlying `V1::CommitResponse` object.
+        # @private
         def initialize grpc
           @grpc = grpc
         end
@@ -74,10 +77,13 @@ module Google
           CommitStats.from_grpc @grpc.commit_stats if @grpc.commit_stats
         end
 
-        ##
-        # @private
-        # Creates a new Commit responsee instance from a
+        # Creates a new `Spanner::CommitResponse` instance from a
         # `Google::Cloud::Spanner::V1::CommitResponse`.
+        #
+        # @param grpc [::Google::Cloud::Spanner::V1::CommitResponse]
+        #   Underlying `V1::CommitResponse` object.
+        # @private
+        # @return [::Google::Cloud::Spanner::CommitResponse]
         def self.from_grpc grpc
           new grpc
         end

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

@@ -81,7 +81,7 @@ module Google
 
         # Creates a new `Spanner::Instance` instance.
         # @param grpc [::Google::Cloud::Spanner::Admin::Instance::V1::Instance]
-        #   The protobuf `V1::Instance` underlying object.
+        #   Underlying `V1::Instance` object.
         # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
         # @private
         def initialize grpc, service
@@ -965,7 +965,7 @@ module Google
         # Creates a new Instance instance from a
         # `Google::Cloud::Spanner::Admin::Instance::V1::Instance`.
         # @param grpc [::Google::Cloud::Spanner::Admin::Instance::V1::Instance]
-        #   The protobuf `V1::Instance` underlying object.
+        #   Underlying `V1::Instance` object.
         # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
         # @private
         # @return [::Google::Cloud::Spanner::Instance]

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

@@ -16,6 +16,7 @@
 require "concurrent"
 require "google/cloud/spanner/errors"
 require "google/cloud/spanner/session"
+require "google/cloud/spanner/session_creation_options"
 
 module Google
   module Cloud
@@ -37,7 +38,9 @@ module Google
         attr_accessor :sessions_in_use
 
         # Creates a new Session pool that manages non-multiplexed sessions.
-        # @param client [::Google::Cloud::Spanner::Client] A `Spanner::Client` reference
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @param session_creation_options [::Google::Cloud::Spanner::SessionCreationOptions] Required.
+        #   Options used for session creation. E.g. session labels.
         # @param min [::Integer] Min number of sessions to keep
         # @param max [::Integer] Max number of sessions to keep
         # @param keepalive [::Numeric] How long after their last usage the sessions can be reclaimed
@@ -46,9 +49,10 @@ module Google
         # @param threads [::Integer, nil] Number of threads in the thread pool that is used for keepalive and
         #   release session actions. If `nil` the Pool will choose a reasonable default.
         # @private
-        def initialize client, min: 10, max: 100, keepalive: 1800,
+        def initialize service, session_creation_options, min: 10, max: 100, keepalive: 1800,
                        fail: true, threads: nil
-          @client = client
+          @service = service
+          @session_creation_options = session_creation_options
           @min = min
           @max = max
           @keepalive = keepalive
@@ -127,7 +131,7 @@ module Google
           nil
         end
 
-        def reset
+        def reset!
           close
           init
 
@@ -137,6 +141,7 @@ module Google
 
           true
         end
+        alias reset reset!
 
         def close
           shutdown
@@ -181,7 +186,7 @@ module Google
           # init the keepalive task
           create_keepalive_task!
           # init session stack
-          @sessions_available = @client.batch_create_new_sessions @min
+          @sessions_available = batch_create_new_sessions @min
           @sessions_in_use = {}
         end
 
@@ -209,7 +214,7 @@ module Google
           end
 
           begin
-            session = @client.create_new_session
+            session = create_new_session
           rescue StandardError => e
             @mutex.synchronize do
               @new_sessions_in_process -= 1
@@ -239,6 +244,60 @@ module Google
         def future(&)
           Concurrent::Future.new(executor: @thread_pool, &).execute
         end
+
+        # Creates a new `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
+          )
+
+          Session.from_grpc grpc, @service, query_options: @query_options
+        end
+
+        # Creates a batch of new session objects of size `total`.
+        # Makes multiple RPCs if necessary. Returns empty array if total is 0.
+        # @private
+        # @return [::Array<::Google::Cloud::Spanner::Session>]
+        def batch_create_new_sessions total
+          sessions = []
+          remaining = total
+          while remaining.positive?
+            sessions += batch_create_sessions remaining
+            remaining = total - sessions.count
+          end
+          sessions
+        end
+
+        # Tries to creates a batch of new session objects of size `session_count`.
+        # The response may have fewer sessions than requested in the RPC.
+        # @private
+        # @return [::Array<::Google::Cloud::Spanner::Session>]
+        def batch_create_sessions session_count
+          ensure_service!
+          resp = @service.batch_create_sessions(
+            @session_creation_options.database_path,
+            session_count,
+            labels:  @session_creation_options.session_labels,
+            database_role: @session_creation_options.session_creator_role
+          )
+
+          resp.session.map do |grpc|
+            Session.from_grpc grpc, @service, query_options: @query_options
+          end
+        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