google-cloud-spanner 2.26.0 → 2.28.0

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
@@ -221,8 +236,8 @@ module Google
           @keepalive_task.execute
         end
 
-        def future &block
-          Concurrent::Future.new(executor: @thread_pool, &block).execute
+        def future(&)
+          Concurrent::Future.new(executor: @thread_pool, &).execute
         end
       end
     end

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? "/"