google-cloud-spanner 2.26.0 → 2.28.0

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.26.0".freeze
+      VERSION = "2.28.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.26.0
+  version: 2.28.0
 platform: ruby
 authors:
 - Mike Moore
 - Chris Smith
 bindir: bin
 cert_chain: []
-date: 2025-03-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -150,6 +150,7 @@ files:
 - lib/google/cloud/spanner/instance/config/list.rb
 - lib/google/cloud/spanner/instance/job.rb
 - lib/google/cloud/spanner/instance/list.rb
+- lib/google/cloud/spanner/interval.rb
 - lib/google/cloud/spanner/lar_headers.rb
 - lib/google/cloud/spanner/mutation_group.rb
 - lib/google/cloud/spanner/partition.rb
@@ -175,14 +176,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.9
 specification_version: 4
 summary: API Client library for Google Cloud Spanner API
 test_files: []