google-cloud-spanner 2.27.0 → 2.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2950745d1ef3cf6be982e2bc64a29ce467e8a15710293265181d41dd138a80ad
-  data.tar.gz: 6e96c531e76300e6d77d5d261ec0d09da96157f82aa3f4c32c502b52ce6b6f74
+  metadata.gz: 850ac8a54d873ff6d92cc7d7b835abd1d0fd980d22529296b036b67d5c4ecbfe
+  data.tar.gz: 585441baf49b27942fddc9876044221965fe9edd475bdf8f6c53f463a3a75cf0
 SHA512:
-  metadata.gz: 55291fac48fb628c64d4df17266cf1a07babbd918b8411e7116e8ba23b0430c20dbf0f210098f27052bbcd9d97c9e3ed0ec2937a4c342cb5994946df2dcf2ac6
-  data.tar.gz: b2e91d7c79a316a69b3657eace1232936a13013236117170b974a9487e0d9fdd5c9de34bba851ffbe310a26c6864954fd94de68df91fdb1a9d64bd06773d5aff
+  metadata.gz: dca36d5f2479c792b0c7e10051cf52915314c76de12581d09ff8284ae8e591430d2d67f779c71b2956580e4f970054ddcac3d3f8429ed8ced759b8cd0be0339a
+  data.tar.gz: 887212c39b640de69edf12df3bca506494a7bb65c6f0b102eb80cefb3c41e8c3511b027f18334669ab58a9d1ba7114ab1d5bdc83d4982c39521ff4d542b94344

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Release History
 
+### 2.28.0 (2025-10-22)
+
+#### Features
+
+* Add support for order_by and lock_hint options ([#182](https://github.com/googleapis/ruby-spanner/issues/182))
+ 
+#### Bug Fixes
+
+* use create Transaction when retrying when enumerating rows in `Spanner::Results` ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* run explicit BeginTransaction in Client#transaction for mutation-only payloads ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* Transaction#initialize is no longer incorrectly marked as public in documentation ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* several field accessors in Partition are no longer incorrectly marked as public in documentation ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* session keepalive uses Process.clock_gettime instead of Time.now ([#185](https://github.com/googleapis/ruby-spanner/pull/185)) 
+
 ### 2.27.0 (2025-05-28)
 
 #### Features

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

@@ -33,8 +33,9 @@ module Google
           #   {Google::Cloud::Spanner::Admin::Database.database_admin}.list_backup_operations instead.
           #
           class List < DelegateClass(::Array)
+            # The `Spanner::Service` reference.
             # @private
-            # The gRPC Service object.
+            # @return [::Google::Cloud::Spanner::Service]
             attr_accessor :service
 
             # @private
@@ -148,13 +149,14 @@ module Google
               end
             end
 
-            ##
-            # @private
-            #
-            # New Backup::Job::List from a
+            # Creates a new `Spanner::Backup::Job::List` of `Gapic::Operation` operations from a
             # `Gapic::PagedEnumerable<Google::Longrunning::Operation>`
             # object. Operation object is a backup operation.
-            #
+            # @param grpc [::Gapic::PagedEnumerable<::Google::Longrunning::Operation>]
+            #   Wrapped `Gapic::PagedEnumberable` reference.
+            # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+            # @private
+            # @return [::Google::Cloud::Spanner::Backup::Job::List]
             def self.from_grpc grpc, service
               operations_client =
                 service.databases.instance_variable_get "@operations_client"

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

@@ -58,12 +58,14 @@ module Google
         #   end
         #
         class Job
-          ##
-          # @private The `Gapic::Operation` gRPC object.
+          # The wrapped `Gapic::Operation` object.
+          # @private
+          # @return [::Gapic::Operation]
           attr_accessor :grpc
 
-          ##
-          # @private The gRPC Service object.
+          # The `Spanner::Service` reference.
+          # @private
+          # @return [::Google::Cloud::Spanner::Service]
           attr_accessor :service
 
           ##
@@ -265,8 +267,11 @@ module Google
             Convert.timestamp_to_time @grpc.metadata.cancel_time
           end
 
-          ##
-          # @private New Backup::Job from a `Gapic::Operation` object.
+          # Create a new Backup::Job from a `Gapic::Operation` object.
+          # @param grpc [::Gapic::Operation`] The wrapped `Gapic::Operation` object.
+          # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+          # @private
+          # @return [::Google::Cloud::Spanner::Backup::Job]
           def self.from_grpc grpc, service
             new.tap do |job|
               job.instance_variable_set :@grpc, grpc

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

@@ -63,8 +63,18 @@ module Google
       #     new_partition
       #
       class BatchClient
-        ##
-        # @private Creates a new Spanner BatchClient instance.
+        # Creates a new Spanner BatchClient instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @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 query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example parameter `:optimizer_version`.
+        # @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
         def initialize project, instance_id, database_id, session_labels: nil,
                        query_options: nil, directed_read_options: nil
           @project = project
@@ -404,15 +414,18 @@ module Google
 
         protected
 
-        ##
-        # @private Raise an error unless an active connection to the service is
+        # Raise an error unless an active connection to the service is
         # available.
+        # @private
+        # @raise [StandardError]
+        # @return [nil]
         def ensure_service!
           raise "Must have active connection to service" unless @project.service
         end
 
-        ##
         # New session for each use.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
         def session
           ensure_service!
           grpc = @project.service.create_session \

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

@@ -51,12 +51,26 @@ module Google
       #   end
       #
       class Client
-        ##
+        # A semi-arbitrary constant for thread-wide global parameter name
         # @private
         IS_TRANSACTION_RUNNING_KEY = "ruby_spanner_is_transaction_running".freeze
 
-        ##
-        # @private Creates a new Spanner Client instance.
+        # Creates a new Spanner Client instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @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 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.
+        #   Example: `analyst`
+        # @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
         def initialize project, instance_id, database_id, session_labels: nil,
                        pool_opts: {}, query_options: nil, database_role: nil,
                        directed_read_options: nil
@@ -89,7 +103,7 @@ module Google
         end
 
         # The Spanner project connected to.
-        # @return [Project]
+        # @return [::Google::Cloud::Spanner::Project]
         def project
           @project
         end
@@ -878,6 +892,14 @@ module Google
         #      and all replicas are exhausted without finding a healthy replica,
         #      Spanner will wait for a replica in the list to become available,
         #      requests may fail due to DEADLINE_EXCEEDED errors.
+        # @param [::Google::Cloud::Spanner::V1::ReadRequest::OrderBy] order_by An option to control the order in which
+        #   rows are returned from a read.
+        #   To see the available options refer to
+        #   [Google::Cloud::Spanner::V1::ReadRequest::OrderBy](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-ReadRequest-OrderBy)
+        # @param [::Google::Cloud::Spanner::V1::ReadRequest::LockHint] lock_hint A lock hint mechanism for reads done
+        #   within a transaction.
+        #   To see the available options refer to
+        #   [Google::Cloud::Spanner::V1::ReadRequest::LockHint](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-ReadRequest-LockHint)
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read.
         #
@@ -962,7 +984,7 @@ module Google
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
                  single_use: nil, request_options: nil, call_options: nil,
-                 directed_read_options: nil
+                 directed_read_options: nil, order_by: nil, lock_hint: nil
           validate_single_use_args! single_use
           ensure_service!
 
@@ -981,7 +1003,9 @@ module Google
                               request_options: request_options,
                               call_options: call_options,
                               directed_read_options: directed_read_options || @directed_read_options,
-                              route_to_leader: route_to_leader
+                              route_to_leader: route_to_leader,
+                              order_by: order_by,
+                              lock_hint: lock_hint
           end
           results
         end
@@ -2102,15 +2126,28 @@ module Google
             begin
               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,
+
+              unless tx.existing_transaction?
+                # This can 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,
+                  call_options: call_options
+                )
+              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
+              )
               resp = CommitResponse.from_grpc commit_resp
               commit_options ? resp : resp.timestamp
             rescue GRPC::Aborted,
@@ -2409,17 +2446,21 @@ module Google
           @pool.reset
         end
 
-        ##
+        # Creates a new Session objece.
+        # @param multiplexed [::Boolean] Optional. Default to `false`.
+        #   If `true`, specifies a multiplexed session.
         # @private
-        # Creates a new session object every time.
-        def create_new_session
+        # @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
+            database_role: @database_role,
+            multiplexed: multiplexed
+
           Session.from_grpc grpc, @project.service, query_options: @query_options
         end
 

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

@@ -74,11 +74,16 @@ module Google
       #   end
       #
       class Instance
-        ##
-        # @private The gRPC Service object.
+        # The `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
         attr_accessor :service
 
-        # @private Creates a new Instance instance.
+        # Creates a new `Spanner::Instance` instance.
+        # @param grpc [::Google::Cloud::Spanner::Admin::Instance::V1::Instance]
+        #   The protobuf `V1::Instance` underlying object.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @private
         def initialize grpc, service
           @grpc = grpc
           @service = service
@@ -957,9 +962,13 @@ module Google
           grpc.permissions
         end
 
-        ##
-        # @private Creates a new Instance instance from a
+        # 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.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Instance]
         def self.from_grpc grpc, service
           new grpc, service
         end

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

@@ -75,7 +75,7 @@ module Google
               (?:T(?!$)
               (?:(?<hours>-?\d+)H)?
               (?:(?<minutes>-?\d+)M)?
-              (?:(?<seconds>-?(?!S)\d*(?:[\.,]\d{1,9})?)S)?)?
+              (?:(?<seconds>-?(?!S)\d*(?:[.,]\d{1,9})?)S)?)?
               $
             /x
             interval_months = 0

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

@@ -44,8 +44,14 @@ module Google
       #   results = batch_snapshot.execute_partition partition
       #
       class Partition
-        # @ private
+        # A `V1::ExecuteSqlRequest` that is related to this partition.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::ExecuteSqlRequest]
         attr_reader :execute
+
+        # A `V1::ReadRequest` that is related to this partition.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::ReadRequest]
         attr_reader :read
 
         ##

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

@@ -36,6 +36,16 @@ module Google
         # and `Session` objects as values.
         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 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
+        # @param fail [::Boolean] If `true` the pool will raise `SessionLimitError` if number of new sessions
+        #   needed is more that can be created due to the `max` parameter. If `false` it will wait instead.
+        # @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,
                        fail: true, threads: nil
           @client = client
@@ -52,6 +62,11 @@ module Google
           init
         end
 
+        # Provides a session for running an operation
+        # @yield session Session a client can use to run an operation
+        # @yieldparam [::Google::Cloud::Spanner::Session] `Spanner::Session` to run an operation
+        # @private
+        # @return [nil]
         def with_session
           session = checkout_session
           begin

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

@@ -66,12 +66,22 @@ module Google
       #   end
       #
       class Project
-        ##
-        # @private The Service object.
-        attr_accessor :service, :query_options
+        # The `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
+        attr_accessor :service
 
-        ##
-        # @private Creates a new Spanner Project instance.
+        # A hash of values to specify the custom query options for executing SQL query.
+        # Example option: `:optimizer_version`.
+        # @private
+        # @return [::Hash, nil]
+        attr_accessor :query_options
+
+        # Creates a new Spanner Project instance.
+        # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` ref.
+        # @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 service, query_options: nil
           @service = service
           @query_options = query_options
@@ -80,6 +90,8 @@ module Google
         ##
         # The identifier for the Cloud Spanner project.
         #
+        # @return [::String]
+        #
         # @example
         #   require "google/cloud"
         #

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

@@ -40,19 +40,44 @@ module Google
       #     puts "Column #{name} is type #{type}"
       #   end
       #
+      #   results.rows.each do |row|
+      #     puts "User #{row[:id]} is #{row[:name]}"
+      #   end
+      #
       class Results
-        ##
-        # @private Object of type
-        # Google::Cloud::Spanner::V1::ResultSetMetadata
+        # The `V1::ResultSetMetadata` protobuf object from the first
+        # PartialResultSet.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::ResultSetMetadata]
         attr_reader :metadata
 
+        # Creates a new Results instance.
+        # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` reference.
+        # @param partial_result_sets [::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>]
+        #   Raw enumerable from grpc `StreamingRead` call.
+        # @param session_name [::String] Required.
+        #   The session in which the transaction to be committed is running.
+        #   Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        # @param metadata [::Google::Cloud::Spanner::V1::ResultSetMetadata] ParialResultSet metadata object
+        # @param stats [::Google::Cloud::Spanner::V1::ResultSetStats] Query plan and execution statistics
+        #   for the statement that produced this streaming result set.
+        # @private
+        def initialize service, partial_result_sets, session_name, metadata, stats
+          @service = service
+          @partial_result_sets = partial_result_sets
+          @session_name = session_name
+          @metadata = metadata
+          @stats = stats
+        end
+
         ##
         # The read timestamp chosen for single-use snapshots (read-only
         # transactions).
         # @return [Time] The chosen timestamp.
         def timestamp
-          return nil if @metadata.nil? || @metadata.transaction.nil?
-          Convert.timestamp_to_time @metadata.transaction.read_timestamp
+          return nil if transaction.nil?
+          Convert.timestamp_to_time transaction.read_timestamp
         end
 
         ##
@@ -78,9 +103,9 @@ module Google
           @fields ||= Fields.from_grpc @metadata.row_type.fields
         end
 
-        ##
+        # Returns a transaction from the first ResultSet's metadata if available
         # @private
-        # Returns a transaction if available
+        # @return [::Google::Cloud::Spanner::V1::Transaction, nil]
         def transaction
           @metadata&.transaction
         end
@@ -128,16 +153,18 @@ module Google
           loop do
             begin
               if should_resume_request
-                @enum = resume_request(resume_token)
+                @partial_result_sets = resume_request(resume_token)
                 buffered_responses = []
                 should_resume_request = false
               elsif should_retry_request
-                @enum = retry_request()
+                @partial_result_sets = retry_request()
                 buffered_responses = []
                 should_retry_request = false
               end
 
-              grpc = @enum.next
+              # @type [::Google::Cloud::Spanner::V1::PartialResultsSet]
+              grpc = @partial_result_sets.next
+
               # metadata should be set before the first iteration...
               @metadata ||= grpc.metadata
               @stats ||= grpc.stats
@@ -243,13 +270,13 @@ module Google
         def resume_request resume_token
           if @execute_query_options
             @service.execute_streaming_sql(
-              @session_path,
+              @session_name,
               @sql,
               **@execute_query_options.merge(resume_token: resume_token)
             )
           else
             @service.streaming_read_table(
-              @session_path,
+              @session_name,
               @table,
               @columns,
               **@read_options.merge(resume_token: resume_token)
@@ -262,9 +289,9 @@ module Google
         # Retries a request, by re-executing it from scratch.
         def retry_request
           if @execute_query_options
-            @service.execute_streaming_sql @session_path, @sql, **@execute_query_options
+            @service.execute_streaming_sql @session_name, @sql, **@execute_query_options
           else
-            @service.streaming_read_table @session_path, @table, @columns, **@read_options
+            @service.streaming_read_table @session_name, @table, @columns, **@read_options
           end
         end
 
@@ -295,35 +322,80 @@ module Google
           @stats.row_count == :row_count_exact
         end
 
+        # Creates a `Spanner::Results` for a given `PartialResultSet` grpc stream.
+        # @param partial_result_sets [::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>]
+        #   Raw enumerable from underlying grpc call.
+        # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` reference.
+        # @param session_name [::String] Required.
+        #   The session in which the transaction to be committed is running.
+        #   Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
         # @private
-        def self.from_enum enum, service
-          grpc = enum.peek
-          new.tap do |results|
-            results.instance_variable_set :@metadata, grpc.metadata
-            results.instance_variable_set :@stats,    grpc.stats
-            results.instance_variable_set :@enum,     enum
-            results.instance_variable_set :@service,  service
-          end
+        # @return [::Google::Cloud::Spanner::Results]
+        def self.from_partial_result_sets partial_result_sets, service, session_name
+          # @type [::Google::Cloud::Spanner::V1::PartialResultSet]
+          partial_result_set = partial_result_sets.peek
+          metadata = partial_result_set.metadata
+          stats = partial_result_set.stats
+          new service, partial_result_sets, session_name, metadata, stats
         rescue GRPC::BadStatus => e
           raise Google::Cloud::Error.from_error(e)
         end
 
+        # Creates a `Spanner::Results` wrapper from ExecuteStreamingSql call results and params.
+        # @param response [::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>]
+        #   Raw enumerable from grpc `ExecuteStreamingSql` call.
+        # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` reference.
+        # @param session_name [::String] Required.
+        #   The session in which the transaction to be committed is running.
+        #   Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        # @param sql [::String] The SQL query string that was executed.
+        # @param execute_query_options [::Hash] Full request options
+        #   that were sent to the `service.execute_streaming_sql`. This hash joins params needed to
+        #   construct `::Gapic::CallOptions`, e.g. `call_options` and header-related `route_to_leader`
+        #   with params specific to `execute_streaming_sql`, such as `seqno`.
         # @private
-        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
+        # @return [::Google::Cloud::Spanner::Results]
+        def self.from_execute_query_response response, service, session_name, sql, execute_query_options
+          from_partial_result_sets(response, service, session_name).tap do |results|
+            execute_query_options_copy = execute_query_options.dup
+            unless results.metadata.transaction.nil?
+              execute_query_options_copy[:transaction] = V1::TransactionSelector.new id: results.metadata.transaction.id
+            end
+
             results.instance_variable_set :@sql, sql
-            results.instance_variable_set :@execute_query_options, execute_query_options
+            results.instance_variable_set :@execute_query_options, execute_query_options_copy
           end
         end
 
+        # Creates a `Spanner::Results` wrapper from StreamingRead call results and params.
+        # @param response [::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>]
+        #   Raw enumerable from grpc `StreamingRead` call.
+        # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` reference.
+        # @param session_name [::String] Required.
+        #   The session in which the transaction to be committed is running.
+        #   Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        # @param table [::String] The name of the table in the database that was read by `StreamingRead` request.
+        # @param columns [::Array<String, Symbol>] The columns of table that were returned
+        #   by the `StreamingRead` request.
+        # @param read_options [::Hash] Full request options
+        #   that were sent to the `service.streaming_read_table`. This hash joins params needed to
+        #   construct `::Gapic::CallOptions`, e.g. `call_options` and header-related `route_to_leader`
+        #   with params specific to `streaming_read_table`, such as `keys`.
         # @private
-        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
+        # @return [::Google::Cloud::Spanner::Results]
+        def self.from_read_response response, service, session_name, table, columns, read_options
+          from_partial_result_sets(response, service, session_name).tap do |results|
+            read_options_copy = read_options.dup
+            unless results.metadata.transaction.nil?
+              read_options_copy[:transaction] = V1::TransactionSelector.new id: results.metadata.transaction.id
+            end
+
             results.instance_variable_set :@table, table
             results.instance_variable_set :@columns, columns
-            results.instance_variable_set :@read_options, read_options
+            results.instance_variable_set :@read_options, read_options_copy
           end
         end
 

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

@@ -43,8 +43,18 @@ module Google
         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.
+        # Creates a new `Spanner::Service` instance.
+        # @param project [::String] The project id to use
+        # @param credentials [::Symbol, ::Google::Auth::Credentials] Credentials
+        # @param quota_project [::String, nil] Optional. The quota project id to use
+        # @param host [::String, nil] Optional. The endpoint override.
+        # @param timeout [::Numeric, nil] Optional. Timeout for Gapic client.
+        # @param lib_name [::String, nil] Optional. Library name for headers.
+        # @param lib_version [::String, nil] Optional. Library version for headers.
+        # @param enable_leader_aware_routing [::Boolean, nil] Optional. Whether Leader
+        #   Aware Routing should be enabled.
+        # @param universe_domain [::String, nil] Optional. The domain of the universe to connect to.
+        # @private
         def initialize project, credentials, quota_project: nil,
                        host: nil, timeout: nil, lib_name: nil, lib_version: nil,
                        enable_leader_aware_routing: nil, universe_domain: nil
@@ -82,6 +92,8 @@ module Google
             GRPC::Core::CallCredentials.new credentials.client.updater_proc
         end
 
+        # `V1::Spanner::Client` or a mock.
+        # @return [::Google::Cloud::Spanner::V1::Spanner::Client]
         def service
           return mocked_service if mocked_service
           @service ||=
@@ -145,6 +157,11 @@ module Google
           paged_enum.response
         end
 
+        # Gets information about a particular instance
+        # @param name [::String] The name of the Spanner instance, e.g. 'myinstance'
+        #   or path to the Spanner instance, e.g. `projects/myproject/instances/myinstance`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Admin::Instance::V1::Instance]
         def get_instance name, call_options: nil
           opts = default_options call_options: call_options
           request = { name: instance_path(name) }
@@ -329,13 +346,41 @@ module Google
           service.get_session({ name: session_name }, opts)
         end
 
+        # Creates a new Spanner session.
+        # This creates a `V1::Session` protobuf object not wrapped in `Spanner::Session`.
+        #
+        # @param database_name [::String] The full name of the database.
+        # @param labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @param database_role [::String, nil] Optional. The Spanner session creator role.
+        #   Example: `analyst`.
+        # @param multiplexed [::Boolean] Optional. Default to `false`.
+        #   If `true`, specifies a multiplexed session.
+        # @return [::Google::Cloud::Spanner::V1::Session]
+        # @private
         def create_session database_name, labels: nil,
-                           call_options: nil, database_role: nil
+                           call_options: nil, database_role: nil,
+                           multiplexed: false
           route_to_leader = LARHeaders.create_session
-          opts = default_options session_name: database_name,
-                                 call_options: call_options,
-                                 route_to_leader: route_to_leader
-          session = V1::Session.new labels: labels, creator_role: database_role if labels || database_role
+          opts = default_options(
+            session_name: database_name,
+            call_options: call_options,
+            route_to_leader: route_to_leader
+          )
+
+          # check if we need a session object in request or server defaults would work.
+          params_diff_from_default = !(labels.nil? && database_role.nil? && !multiplexed)
+
+          if params_diff_from_default
+            session = V1::Session.new(
+              labels: labels,
+              creator_role: database_role,
+              multiplexed: multiplexed
+            )
+          end
+
           service.create_session(
             { database: database_name, session: session }, opts
           )
@@ -414,7 +459,7 @@ module Google
                                  resume_token: nil, partition_token: nil,
                                  request_options: nil, call_options: nil,
                                  data_boost_enabled: nil, directed_read_options: nil,
-                                 route_to_leader: nil
+                                 route_to_leader: nil, order_by: nil, lock_hint: nil
           opts = default_options session_name: session_name,
                                  call_options: call_options,
                                  route_to_leader: route_to_leader
@@ -422,7 +467,8 @@ module Google
             session: session_name, table: table_name, columns: columns,
             key_set: keys, transaction: transaction, index: index,
             limit: limit, resume_token: resume_token,
-            partition_token: partition_token, request_options: request_options
+            partition_token: partition_token, request_options: request_options,
+            order_by: order_by, lock_hint: lock_hint
           }
           request[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
           request[:directed_read_options] = directed_read_options unless directed_read_options.nil?
@@ -463,6 +509,29 @@ module Google
           service.partition_query request, opts
         end
 
+        # Commits a transaction. Can be a predefined (`transaction_id`) transaction
+        # or a single-use created for this request. The request includes the mutations to be
+        # applied to rows in the database.
+        #
+        # @param session_name [::String]
+        #   Required. The session in which the transaction to be committed is running.
+        # @param mutations [::Array<::Google::Cloud::Spanner::V1::Mutation>] Optional.
+        #   The mutations to be executed when this transaction commits. All
+        #   mutations are applied atomically, in the order they appear in
+        #   this list. Defaults to an empty array.
+        # @param transaction_id [::String, nil] Optional.
+        #   Commit a previously-started transaction. If nil, a new single-use transation will be used.
+        # @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 commit_options [::Hash, nil]  Optional. A hash of commit options.
+        #   Example option: `:return_commit_stats`.
+        # @param request_options [::Hash, nil] Optional. Common request options.
+        #   Example option: `:priority`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::CommitResponse]
         def commit session_name, mutations = [],
                    transaction_id: nil, exclude_txn_from_change_streams: false,
                    commit_options: nil, request_options: nil, call_options: nil
@@ -484,10 +553,16 @@ module Google
           }
 
           request = add_commit_options request, commit_options
-
+          # request is a hash equivalent of `::Google::Cloud::Spanner::V1::CommitRequest`
           service.commit request, opts
         end
 
+        # Merges commit options hash to a hash representing a `V1::CommitRequest`.
+        # @param request [::Hash] A `::Google::Cloud::Spanner::V1::CommitRequest` in a hash form.
+        # @param commit_options [::Hash, nil]  Optional. A hash of commit options.
+        #   Example option: `:return_commit_stats`.
+        # @return [::Hash] An enriched `::Google::Cloud::Spanner::V1::CommitRequest` in a hash form.
+        # @private
         def add_commit_options request, commit_options
           if commit_options
             if commit_options.key? :return_commit_stats
@@ -512,6 +587,38 @@ module Google
           service.rollback request, opts
         end
 
+        # Explicitly begins a new transaction, making a `BeginTransaction` rpc call,
+        # and creating and returning a `V1::Transaction` object.
+        #
+        # Explicit transaction creation can often be skipped:
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#read Read},
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql} and
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_batch_dml ExecuteBatchDml}
+        # can begin a new transaction as part of the request (so-called inline-begin).
+        # The inline-begin functionality is used in methods on `Spanner::Transaction` class,
+        # e.g. `Spanner::Transaction#read`, accessible to the end-users via the `Spanner::Client#transaction` method.
+        #
+        # All the above methods, and  {::Google::Cloud::Spanner::V1::Spanner::Client#commit Commit}
+        # can utilize single-use transactions that do not require an explicit BeginTransaction call.
+        # Single-use transactions are used by the methods on `Spanner::Client` class,
+        # e.g. `Spanner::Client#read`, with the exception of `Spanner::Client#transaction`.
+        #
+        # @param session_name [::String]
+        #   Required. The session in which the transaction is to be created.
+        #   Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        # @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 request_options [::Hash, nil] Optional. Common request options.
+        #   Example option: `:priority`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @param route_to_leader [::String, nil] Optional. The value to be sent
+        #   as `x-goog-spanner-route-to-leader` header for leader aware routing.
+        #   Expected values: `"true"` or `"false"`.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::Transaction]
         def begin_transaction session_name,
                               exclude_txn_from_change_streams: false,
                               request_options: nil,
@@ -647,6 +754,25 @@ module Google
           databases.list_database_operations request, opts
         end
 
+        # Lists the backup `::Google::Longrunning::Operation` long-running operations in
+        # the given instance. A backup operation has a name of the form
+        # projects/<project>/instances/<instance>/backups/<backup>/operations/<operation>.
+        # @param instance_id [::String] The name of the Spanner instance, e.g. 'myinstance'
+        #   or path to the Spanner instance, e.g. `projects/myproject/instances/myinstance`.
+        # @param filter [::String, nil] Optional.
+        #   An expression that filters the list of returned backup operations.
+        #   Example filter: `done:true`.
+        # @param page_size [::Integer, nil] Optional.
+        #   Number of operations to be returned in the response. If 0 or
+        #   less, defaults to the server's maximum allowed page size.
+        # @param page_token [::String, nil] Optional.
+        #   If set, `page_token` should contain a value received as a `next_page_token`
+        #   from a previous `ListBackupOperationsResponse` to the same `parent`
+        #   and with the same `filter`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @private
+        # @return [::Gapic::PagedEnumerable<::Gapic::Operation>]
         def list_backup_operations instance_id,
                                    filter: nil, page_size: nil,
                                    page_token: nil,
@@ -736,6 +862,12 @@ module Google
             project: project
         end
 
+        # Converts an instance name to instance path.
+        # If an instance path is given, returns it unchanged
+        # @param name [::String] name of the Spanner instance, e.g. 'myinstance'
+        #   or path to the Spanner instance, e.g. `projects/myproject/instances/myinstance`.
+        # @private
+        # @return [::String]
         def instance_path name
           return name if name.to_s.include? "/"
 

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

@@ -43,19 +43,28 @@ module Google
       # no operations are sent for more than an hour.
       #
       class Session
-        ##
-        # @private The `Google::Cloud::Spanner::V1::Session` object
+        # The wrapped `V1::Session` protobuf session object.
+        # @return [::Google::Cloud::Spanner::V1::Session]
+        # @private
         attr_accessor :grpc
 
-        ##
-        # @private The gRPC Service object.
+        # The `Spanner::Service` object.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
         attr_accessor :service
 
-        ##
-        # @private The hash of query options.
+        # A hash of values to specify the custom query options for executing SQL query.
+        # Example option: `:optimizer_version`.
+        # @private
+        # @return [::Hash, nil]
         attr_accessor :query_options
 
-        # @private Creates a new Session instance.
+        # Creates a new Session instance.
+        # @param grpc [::Google::Cloud::Spanner::V1::Session] Underlying `V1::Session` object.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` object.
+        # @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 grpc, service, query_options: nil
           @grpc = grpc
           @service = service
@@ -63,33 +72,38 @@ module Google
         end
 
         # The unique identifier for the project.
-        # @return [String]
+        # @private
+        # @return [::String]
         def project_id
           @grpc.name.split("/")[1]
         end
 
         # The unique identifier for the instance.
-        # @return [String]
+        # @private
+        # @return [::String]
         def instance_id
           @grpc.name.split("/")[3]
         end
 
         # The unique identifier for the database.
-        # @return [String]
+        # @private
+        # @return [::String]
         def database_id
           @grpc.name.split("/")[5]
         end
 
         # The unique identifier for the session.
-        # @return [String]
+        # @private
+        # @return [::String]
         def session_id
           @grpc.name.split("/")[7]
         end
 
-        ##
-        # The full path for the session resource. Values are of the form
+        # Full session name.
+        # Values are of the form:
         # `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
-        # @return [String]
+        # @private
+        # @return [::String]
         def path
           @grpc.name
         end
@@ -360,7 +374,7 @@ module Google
           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
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           results
         end
 
@@ -430,7 +444,7 @@ module Google
                                               batch.statements, seqno,
                                               request_options: request_options,
                                               call_options: call_options
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           results
         end
 
@@ -483,6 +497,14 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [::Google::Cloud::Spanner::V1::ReadRequest::OrderBy] order_by An option to control the order in which
+        #   rows are returned from a read.
+        #   To see the available options refer to
+        #   ['Google::Cloud::Spanner::V1::ReadRequest::OrderBy'](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-ReadRequest-OrderBy)
+        # @param [::Google::Cloud::Spanner::V1::ReadRequest::LockHint] lock_hint A lock hint mechanism for reads done
+        #   within a transaction.
+        #   To see the available options refer to
+        #   ['Google::Cloud::Spanner::V1::ReadRequest::LockHint'](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-ReadRequest-LockHint)
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read
         #   operation.
@@ -503,7 +525,7 @@ module Google
         def read table, columns, keys: nil, index: nil, limit: nil,
                  transaction: nil, partition_token: nil, request_options: nil,
                  call_options: nil, data_boost_enabled: nil, directed_read_options: nil,
-                 route_to_leader: nil
+                 route_to_leader: nil, order_by: nil, lock_hint: nil
           ensure_service!
 
           read_options = {
@@ -512,7 +534,9 @@ module Google
             partition_token: partition_token,
             request_options: request_options,
             call_options: call_options,
-            route_to_leader: route_to_leader
+            route_to_leader: route_to_leader,
+            order_by: order_by,
+            lock_hint: lock_hint
           }
           read_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
           read_options[:directed_read_options] = directed_read_options unless directed_read_options.nil?
@@ -522,7 +546,7 @@ module Google
 
           results = Results.from_read_response response, service, path, table, columns, read_options
 
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
 
           results
         end
@@ -538,7 +562,7 @@ module Google
                                     max_partitions: max_partitions,
                                     call_options: call_options
 
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
 
           results
         end
@@ -555,7 +579,7 @@ module Google
             max_partitions: max_partitions,
             call_options: call_options
 
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
 
           results
         end
@@ -657,7 +681,7 @@ module Google
                                        commit_options: commit_options,
                                        request_options: request_options,
                                        call_options: call_options
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           resp = CommitResponse.from_grpc commit_resp
           commit_options ? resp : resp.timestamp
         end
@@ -755,7 +779,7 @@ module Google
                                          request_options: request_options,
                                          call_options: call_options
           results = BatchWriteResults.new response
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           results
         end
 
@@ -1341,7 +1365,7 @@ module Google
         # Rolls back the transaction, releasing any locks it holds.
         def rollback transaction_id
           service.rollback path, transaction_id
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           true
         end
 
@@ -1370,7 +1394,7 @@ module Google
         def reload!
           ensure_service!
           @grpc = service.get_session path
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           self
         rescue Google::Cloud::NotFoundError
           labels = @grpc.labels.to_h unless @grpc.labels.to_h.empty?
@@ -1379,7 +1403,7 @@ module Google
               project: project_id, instance: instance_id, database: database_id
             ),
             labels: labels
-          @last_updated_at = Time.now
+          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           self
         end
 
@@ -1408,18 +1432,23 @@ module Google
           service.delete_session path
         end
 
-        ##
-        # @private
         # Determines if the session has been idle longer than the given
         # duration.
-        def idle_since? duration
+        # @param duration_sec [::Numeric] interval in seconds
+        # @private
+        # @return [::Boolean]
+        def idle_since? duration_sec
           return true if @last_updated_at.nil?
-          Time.now > @last_updated_at + duration
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) > @last_updated_at + duration_sec
         end
 
-        ##
-        # @private Creates a new Session instance from a
-        # `Google::Cloud::Spanner::V1::Session`.
+        # Creates a new Session instance from a `V1::Session`.
+        # @param grpc [::Google::Cloud::Spanner::V1::Session] Underlying `V1::Session` object.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` ref.
+        # @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
+        # @return [::Google::Cloud::Spanner::Session]
         def self.from_grpc grpc, service, query_options: nil
           new grpc, service, query_options: query_options
         end
@@ -1439,6 +1468,11 @@ module Google
           raise "Must have active connection to service" unless service
         end
 
+        # Merge two hashes
+        # @param hash [::Hash, nil]
+        # @param hash_to_merge [::Hash, nil]
+        # @private
+        # @return [::Hash, nil]
         def merge_if_present hash, hash_to_merge
           if hash.nil?
             hash_to_merge

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

@@ -76,19 +76,40 @@ module Google
       #   end
       #
       class Transaction
-        # @private The `Google::Cloud::Spanner::V1::Transaction` object.
+        # The underlying `V1::Transaction` protobuf object.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::Transaction]
         attr_reader :grpc
 
-        # @private The Session object.
+        # The `Spanner::Session` session for this transaction.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
         attr_accessor :session
 
-        # @private Transaction tag for statistics collection.
+        # Transaction tag for statistics collection.
+        # Example: `"update_user_profile"`.
+        # @private
+        # @return [::String, nil]
         attr_accessor :transaction_tag
 
-        # @private Whether to exclude from change streams.
+        # Whether to exclude this transaction from change streams.
+        # @private
+        # @return [::Boolean]
         attr_accessor :exclude_txn_from_change_streams
 
-        def initialize
+        # 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.
+        # @private
+        # @return [::Google::Cloud::Spanner::Transaction]
+        def initialize grpc, session, exclude_txn_from_change_streams
+          @grpc = grpc
+          @session = session
+          @exclude_txn_from_change_streams = exclude_txn_from_change_streams
+
           @commit = Commit.new
           @seqno = 0
           @exclude_txn_from_change_streams = false
@@ -116,7 +137,7 @@ module Google
         # @return [String] The transaction id.
         def transaction_id
           return @grpc.id if existing_transaction?
-          safe_begin_transaction
+          safe_begin_transaction!
           @grpc.id
         end
 
@@ -1153,15 +1174,16 @@ module Google
           @commit.mutations
         end
 
-        ##
-        # @private Creates a new Transaction instance from a
-        # `Google::Cloud::Spanner::V1::Transaction`.
+        # 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] 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.
+        # @private
+        # @return [::Google::Cloud::Spanner::Transaction]
         def self.from_grpc grpc, session, exclude_txn_from_change_streams: false
-          new.tap do |s|
-            s.instance_variable_set :@grpc,    grpc
-            s.instance_variable_set :@session, session
-            s.exclude_txn_from_change_streams = exclude_txn_from_change_streams
-          end
+          new grpc, session, exclude_txn_from_change_streams
         end
 
         ##
@@ -1176,6 +1198,33 @@ module Google
           @grpc.nil?
         end
 
+        # Begins a new transaction in a thread-safe manner if one does not already exist.
+        #
+        # @param exclude_from_change_streams [::Boolean] Optional. Defaults to `false`.
+        #   When `exclude_from_change_streams` is set to `true`, it prevents read
+        #   or write transactions from being tracked in change streams.
+        # @param request_options [::Hash, nil] Optional. Common request options.
+        #   Example option: `:priority`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @private
+        # @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
+          @mutex.synchronize do
+            return if existing_transaction?
+            ensure_session!
+            route_to_leader = LARHeaders.begin_transaction true
+            @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
+            )
+          end
+        end
+
         protected
 
         ##
@@ -1203,24 +1252,18 @@ module Google
           end
         end
 
-        ##
-        # Create a new transaction in a thread-safe manner.
-        def safe_begin_transaction
-          @mutex.synchronize do
-            return if existing_transaction?
-            ensure_session!
-            route_to_leader = LARHeaders.begin_transaction true
-            @grpc = service.begin_transaction session.path, route_to_leader: route_to_leader
-          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.
+        # 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.
+        # This method is expected to be called from within `safe_execute()` method's block,
+        # since it provides synchronization and gurantees thread safety.
+        #
+        # @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.
+        # @private
+        # @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?
           V1::TransactionSelector.new(
@@ -1261,6 +1304,9 @@ module Google
           raise "Must have active connection to service" unless session
         end
 
+        # The `Spanner::Service` object used by this transaction.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
         def service
           session.service
         end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.27.0".freeze
+      VERSION = "2.28.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.27.0
+  version: 2.28.0
 platform: ruby
 authors:
 - Mike Moore