google-cloud-spanner 2.29.0 → 2.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c47f3cfa10a6d612de5578cd6602dece290f316246a809a265b504fc74737307
-  data.tar.gz: fe95585faa6210cb5110dbc54e3bb95e0a9126577c1893854880ebd8232946a1
+  metadata.gz: 747996c4ee90317631f8648dbc5abefec1ef5dec80ab4e867475dfc465671cf6
+  data.tar.gz: 7316c929b5c69c3595e35780fe13ced837091de64de0da2ad13e41c2ccab065e
 SHA512:
-  metadata.gz: fa836a8f8a9e7da61b9ca53e655a8ab0870dcc50435756af6d2637931b9f16c1f12853a4eab16038176ca4b85395f6d83d7cbccec9a8c37ad5c562f9ee83ad2e
-  data.tar.gz: 873894c371f0f7e9679a4df3f4b8fdc28e0047f135584b11616bc25f53982ef42b378cd323c3216d2283f6517071d218dc8a1c7a60fb1b842bac9422fa0b3bda
+  metadata.gz: c5f2caed803fc1883c743c34b45a54383259d20749628d01af88cd94d6ac2b89195af9597d763a199b597066a1bee5999fa3b2c3e34b89b59d78c5e86a7cdee1
+  data.tar.gz: 8d40b705e2b0fa7b93f2aa334b8b034ad8cb320833d32d6c0bf7a1073966d6cc9d9b40192a86bd1d3fcacce64c020a60f7b4b4fa6b2b9ffdefbc6f308428b711

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 2.31.0 (2025-12-02)
+
+#### Features
+
+* Support isolation level in Transaction Options ([#206](https://github.com/googleapis/ruby-spanner/issues/206)) 
+
+### 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.
@@ -1053,6 +1067,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1144,13 +1160,15 @@ module Google
         #
         def upsert table, rows,
                    exclude_txn_from_change_streams: false,
-                   commit_options: nil, request_options: nil, call_options: nil
+                   isolation_level: nil, commit_options: nil, request_options: nil,
+                   call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
             session.upsert table, rows,
                            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           isolation_level: isolation_level,
                            commit_options: commit_options,
                            request_options: request_options,
                            call_options: call_options
@@ -1200,6 +1218,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1291,13 +1311,15 @@ module Google
         #
         def insert table, rows,
                    exclude_txn_from_change_streams: false,
-                   commit_options: nil, request_options: nil, call_options: nil
+                   isolation_level: nil, commit_options: nil, request_options: nil,
+                   call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
             session.insert table, rows,
                            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           isolation_level: isolation_level,
                            commit_options: commit_options,
                            request_options: request_options,
                            call_options: call_options
@@ -1346,6 +1368,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1436,13 +1460,15 @@ module Google
         #
         def update table, rows,
                    exclude_txn_from_change_streams: false,
-                   commit_options: nil, request_options: nil, call_options: nil
+                   isolation_level: nil, commit_options: nil, request_options: nil,
+                   call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
             session.update table, rows,
                            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           isolation_level: isolation_level,
                            commit_options: commit_options,
                            request_options: request_options,
                            call_options: call_options
@@ -1493,6 +1519,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1583,10 +1611,12 @@ module Google
         #
         def replace table, rows,
                     exclude_txn_from_change_streams: false,
-                    commit_options: nil, request_options: nil, call_options: nil
+                    isolation_level: nil, commit_options: nil, request_options: nil,
+                    call_options: nil
           @pool.with_session do |session|
             session.replace table, rows,
                             exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                            isolation_level: isolation_level,
                             commit_options: commit_options,
                             request_options: request_options,
                             call_options: call_options
@@ -1616,6 +1646,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1699,13 +1731,15 @@ module Google
         #
         def delete table, keys = [],
                    exclude_txn_from_change_streams: false,
-                   commit_options: nil, request_options: nil, call_options: nil
+                   isolation_level: nil, commit_options: nil, request_options: nil,
+                   call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
             session.delete table, keys,
                            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           isolation_level: isolation_level,
                            commit_options: commit_options,
                            request_options: request_options,
                            call_options: call_options
@@ -1730,6 +1764,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1826,8 +1862,8 @@ module Google
         #   end
         #
         def commit exclude_txn_from_change_streams: false,
-                   commit_options: nil, request_options: nil, call_options: nil,
-                   &block
+                   isolation_level: nil, commit_options: nil, request_options: nil,
+                   call_options: nil, &block
           raise ArgumentError, "Must provide a block" unless block_given?
 
           request_options = Convert.to_request_options \
@@ -1836,8 +1872,11 @@ module Google
           @pool.with_session do |session|
             session.commit(
               exclude_txn_from_change_streams: exclude_txn_from_change_streams,
-              commit_options: commit_options, request_options: request_options,
-              call_options: call_options, &block
+              isolation_level: isolation_level,
+              commit_options: commit_options,
+              request_options: request_options,
+              call_options: call_options,
+              &block
             )
           end
         end
@@ -1943,7 +1982,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 +2168,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 +2180,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 +2211,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 +2238,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 +2327,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 +2507,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 +2531,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]