google-cloud-spanner 2.27.0 → 2.29.0

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/snapshot.rb

@@ -131,6 +131,18 @@ module Google
         #     available optimizer version.
         #   * `:optimizer_statistics_package` (String) Statistics package to
         #     use. Empty to use the database default.
+        # @param [Hash] request_options Common request options.
+        #
+        #   * `:priority` (Symbol) The relative priority for requests.
+        #     The priority acts as a hint to the Cloud Spanner scheduler
+        #     and does not guarantee priority or order of execution.
+        #     Valid values are `:PRIORITY_LOW`, `:PRIORITY_MEDIUM`,
+        #     `:PRIORITY_HIGH`. If priority not set then default is
+        #     `PRIORITY_UNSPECIFIED` is equivalent to `:PRIORITY_HIGH`.
+        #   * `:tag` (String) A per-request tag which can be applied to
+        #     queries or reads, used for statistics collection. Tag must be a
+        #     valid identifier of the form: `[a-zA-Z][a-zA-Z0-9_\-]` between 2
+        #     and 64 characters in length.
         # @param [Hash] call_options A hash of values to specify the custom
         #   call options, e.g., timeout, retries, etc. Call options are
         #   optional. The following settings can be provided:
@@ -304,13 +316,17 @@ module Google
         #   end
         #
         def execute_query sql, params: nil, types: nil, query_options: nil,
-                          call_options: nil, directed_read_options: nil
+                          request_options: nil, call_options: nil,
+                          directed_read_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
+          request_options = Convert.to_request_options request_options,
+                                                       tag_type: :request_tag
           session.execute_query sql, params: params, types: types,
                                      transaction: tx_selector,
                                      query_options: query_options,
+                                     request_options: request_options,
                                      call_options: call_options,
                                      directed_read_options: directed_read_options || @directed_read_options
         end
@@ -334,6 +350,18 @@ module Google
         #   Optional.
         # @param [Integer] limit If greater than zero, no more than this number
         #   of rows will be returned. The default is no limit.
+        # @param [Hash] request_options Common request options.
+        #
+        #   * `:priority` (Symbol) The relative priority for requests.
+        #     The priority acts as a hint to the Cloud Spanner scheduler
+        #     and does not guarantee priority or order of execution.
+        #     Valid values are `:PRIORITY_LOW`, `:PRIORITY_MEDIUM`,
+        #     `:PRIORITY_HIGH`. If priority not set then default is
+        #     `PRIORITY_UNSPECIFIED` is equivalent to `:PRIORITY_HIGH`.
+        #   * `:tag` (String) A per-request tag which can be applied to
+        #     queries or reads, used for statistics collection. Tag must be a
+        #     valid identifier of the form: `[a-zA-Z][a-zA-Z0-9_\-]` between 2
+        #     and 64 characters in length.
         # @param [Hash] call_options A hash of values to specify the custom
         #   call options, e.g., timeout, retries, etc. Call options are
         #   optional. The following settings can be provided:
@@ -380,7 +408,7 @@ module Google
         #   end
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
-                 call_options: nil, directed_read_options: nil
+                 request_options: nil, call_options: nil, directed_read_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -388,6 +416,7 @@ module Google
 
           session.read table, columns, keys: keys, index: index, limit: limit,
                                        transaction: tx_selector,
+                                       request_options: request_options,
                                        call_options: call_options,
                                        directed_read_options: directed_read_options || @directed_read_options
         end