google-cloud-spanner 1.15.0 → 2.1.0

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

@@ -0,0 +1,169 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "delegate"
+
+module Google
+  module Cloud
+    module Spanner
+      class Backup
+        ##
+        # # List
+        #
+        # Google::Cloud::Spanner::Backup::List is a special case Array with
+        # additional values.
+        #
+        class List < DelegateClass(::Array)
+          # @private
+          # The gRPC Service object.
+          attr_accessor :service
+
+          # @private
+          # The gRPC page enumerable object.
+          attr_accessor :grpc
+
+          ##
+          # @private Create a new Backup::List with an array of
+          # Backup instances.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of backups.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   instance = spanner.instance "my-instance"
+          #   backups = instance.backups
+          #
+          #   if backups.next?
+          #     next_backups = backups.next
+          #   end
+          #
+          def next?
+            grpc.next_page?
+          end
+
+          ##
+          # Retrieve the next page of backups.
+          #
+          # @return [Google::Cloud::Spanner::Backup::List]
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   instance = spanner.instance "my-instance"
+          #   backups = instance.backups
+
+          #   if backups.next?
+          #     next_backups = backups.next
+          #   end
+          #
+          def next
+            ensure_service!
+
+            return nil unless next?
+            grpc.next_page
+            self.class.from_grpc grpc, service
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
+          #
+          # @yield [backup] The block for accessing each backup.
+          # @yieldparam [Google::Cloud::Spanner::Backup] backup The backup
+          #   object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each backup by passing a block:
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   instance = spanner.instance "my-instance"
+          #   backups = instance.backups
+          #
+          #   backups.all do |backup|
+          #     puts backup.backup_id
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   instance = spanner.instance "my-instance"
+          #   backups = instance.backups
+          #
+          #   all_backup_ids = backups.all.map do |backup|
+          #     backup.backup_id
+          #   end
+          #
+          def all
+            return enum_for :all unless block_given?
+
+            results = self
+            loop do
+              results.each { |r| yield r }
+              break unless next?
+              grpc.next_page
+              results = self.class.from_grpc grpc, service
+            end
+          end
+
+          ##
+          # @private
+          # New Backup::List from a
+          # `Gapic::PagedEnumerable<Google::Cloud::Spanner::Admin::Database::V1::Backup>`
+          # object.
+          def self.from_grpc grpc, service
+            backups = List.new(Array(grpc.response.backups).map do |backup|
+              Backup.from_grpc backup, service
+            end)
+
+            backups.grpc = grpc
+            backups.service = service
+            backups
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active service is available.
+          def ensure_service!
+            raise "Must have active connection" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,246 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/spanner/status"
+
+module Google
+  module Cloud
+    module Spanner
+      class Backup
+        class Restore
+          ##
+          # # Job
+          #
+          # A resource representing the long-running, asynchronous processing of
+          # a backup restore. The job can be refreshed to retrieve the restored
+          # database object once the operation has been completed.
+          #
+          # See {Backup#restore}
+          #
+          # @see https://cloud.google.com/spanner/reference/rpc/google.longrunning#google.longrunning.Operation
+          #   Long-running Operation
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   instance = spanner.instance "my-instance"
+          #   backup = instance.backup "my-backup"
+          #   job = backup.restore "my-restored-database"
+          #
+          #   job.done? #=> false
+          #   job.reload! # API call
+          #   job.done? #=> true
+          #
+          #   if job.error?
+          #     status = job.error
+          #   else
+          #     database = job.database
+          #   end
+          #
+          class Job
+            ##
+            # @private The `Gapic::Operation` gRPC object.
+            attr_accessor :grpc
+
+            ##
+            # @private The gRPC Service object.
+            attr_accessor :service
+
+            ##
+            # @private Creates a new Restore::Job instance.
+            def initialize
+              @grpc = nil
+              @service = nil
+            end
+
+            ##
+            # The database is the object of the operation.
+            #
+            # @return [Database, nil] The database instance, or
+            #   `nil` if the operation is not complete.
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #   backup = instance.backup "my-backup"
+            #   job = backup.restore "my-restored-database"
+            #
+            #   job.done? #=> false
+            #   job.reload!
+            #   job.done? #=> true
+            #   database = job.database
+            #
+            def database
+              return nil unless done?
+              return nil unless @grpc.grpc_op.result == :response
+              Database.from_grpc @grpc.results, service
+            end
+
+            ##
+            # Checks if the processing of the restore operation is complete.
+            #
+            # @return [boolean] `true` when complete, `false` otherwise.
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #   backup = instance.backup "my-backup"
+            #   job = backup.restore "my-restored-database"
+            #
+            #   job.done? #=> false
+            #
+            def done?
+              @grpc.done?
+            end
+
+            ##
+            # Checks if the processing of the restore operation has errored.
+            #
+            # @return [boolean] `true` when errored, `false` otherwise.
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #   backup = instance.backup "my-backup"
+            #   job = backup.restore "my-restored-database"
+            #
+            #   job.error? #=> false
+            #
+            def error?
+              @grpc.error?
+            end
+
+            ##
+            # The status if the operation associated with this job produced an
+            # error.
+            #
+            # @return [Google::Cloud::Spanner::Status, nil] A status object with
+            #   the status code and message, or `nil` if no error occurred.
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #   backup = instance.backup "my-backup"
+            #   job = backup.restore "my-restored-database"
+            #
+            #   job.error? # true
+            #
+            #   error = job.error
+            #
+            def error
+              return nil unless error?
+              Google::Cloud::Spanner::Status.from_grpc @grpc.error
+            end
+
+            ##
+            # Reloads the job with current data from the long-running,
+            # asynchronous processing of a restore operation.
+            #
+            # @return [Backup::Job] The same job instance.
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #   backup = instance.backup "my-backup"
+            #   job = backup.restore "my-restored-database"
+            #
+            #   job.done? #=> false
+            #   job.reload! # API call
+            #   job.done? #=> true
+            #
+            def reload!
+              @grpc.reload!
+              self
+            end
+            alias refresh! reload!
+
+            ##
+            # Reloads the job until the operation is complete. The delay between
+            # reloads will incrementally increase.
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #   backup = instance.backup "my-backup"
+            #   job = backup.restore "my-restored-database"
+            #
+            #   job.done? #=> false
+            #   job.wait_until_done!
+            #   job.done? #=> true
+            #
+            def wait_until_done!
+              @grpc.wait_until_done!
+            end
+
+            ##
+            # The operation progress in percentage.
+            #
+            # @return [Integer]
+            def progress_percent
+              @grpc.metadata.progress.progress_percent
+            end
+
+            ##
+            # The operation start time.
+            #
+            # @return [Time, nil]
+            def start_time
+              return nil unless @grpc.metadata.progress.start_time
+              Convert.timestamp_to_time @grpc.metadata.progress.start_time
+            end
+
+            ##
+            # The operation end time.
+            #
+            # @return [Time, nil]
+            def end_time
+              return nil unless @grpc.metadata.progress.end_time
+              Convert.timestamp_to_time @grpc.metadata.progress.end_time
+            end
+
+            ##
+            # @private New Restore::Job from a `Gapic::Operation` object.
+            def self.from_grpc grpc, service
+              new.tap do |job|
+                job.instance_variable_set :@grpc, grpc
+                job.instance_variable_set :@service, service
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -407,8 +407,8 @@ module Google
         def session
           ensure_service!
           grpc = @project.service.create_session \
-            Admin::Database::V1::DatabaseAdminClient.database_path(
-              project_id, instance_id, database_id
+            V1::Spanner::Paths.database_path(
+              project: project_id, instance: instance_id, database: database_id
             ),
             labels: @session_labels
           Session.from_grpc grpc, @project.service, query_options: @query_options

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

@@ -173,6 +173,19 @@ module Google
         #   * `:optimizer_version` (String) The version of optimizer to use.
         #     Empty to use database default. "latest" to use the latest
         #     available optimizer version.
+        # @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:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the query partition.
@@ -196,7 +209,7 @@ module Google
         #
         def partition_query sql, params: nil, types: nil,
                             partition_size_bytes: nil, max_partitions: nil,
-                            query_options: nil
+                            query_options: nil, call_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
@@ -204,10 +217,11 @@ module Google
           results = session.partition_query \
             sql, tx_selector, params: params, types: types,
                               partition_size_bytes: partition_size_bytes,
-                              max_partitions: max_partitions
+                              max_partitions: max_partitions,
+                              call_options: call_options
           results.partitions.map do |grpc|
             # Convert partition protos to execute sql request protos
-            execute_sql_grpc = Google::Spanner::V1::ExecuteSqlRequest.new(
+            execute_sql_grpc = V1::ExecuteSqlRequest.new(
               {
                 session: session.path,
                 sql: sql,
@@ -248,6 +262,19 @@ module Google
         #   partitions to return. For example, this may be set to the number of
         #   workers available. This is only a hint and may provide different
         #   results based on the request.
+        # @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:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the read partition.
@@ -268,7 +295,8 @@ module Google
         #   batch_snapshot.close
         #
         def partition_read table, columns, keys: nil, index: nil,
-                           partition_size_bytes: nil, max_partitions: nil
+                           partition_size_bytes: nil, max_partitions: nil,
+                           call_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -278,11 +306,12 @@ module Google
             table, columns, tx_selector,
             keys: keys, index: index,
             partition_size_bytes: partition_size_bytes,
-            max_partitions: max_partitions
+            max_partitions: max_partitions,
+            call_options: call_options
 
           results.partitions.map do |grpc|
             # Convert partition protos to read request protos
-            read_grpc = Google::Spanner::V1::ReadRequest.new(
+            read_grpc = V1::ReadRequest.new(
               {
                 session: session.path,
                 table: table,
@@ -304,6 +333,19 @@ module Google
         #
         # @param [Google::Cloud::Spanner::Partition] partition The partition to
         #   be executed.
+        # @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:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -320,7 +362,7 @@ module Google
         #
         #   batch_snapshot.close
         #
-        def execute_partition partition
+        def execute_partition partition, call_options: nil
           ensure_session!
 
           partition = Partition.load partition unless partition.is_a? Partition
@@ -329,10 +371,11 @@ module Google
           # TODO: raise if session.path != partition.session
           # TODO: raise if grpc.transaction != partition.transaction
 
+          opts = { call_options: call_options }
           if partition.execute?
-            execute_partition_query partition
+            execute_partition_query partition, opts
           elsif partition.read?
-            execute_partition_read partition
+            execute_partition_read partition, opts
           end
         end
 
@@ -430,6 +473,19 @@ module Google
         #   * `:optimizer_version` (String) The version of optimizer to use.
         #     Empty to use database default. "latest" to use the latest
         #     available optimizer version.
+        # @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:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -549,14 +605,40 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
-        def execute_query sql, params: nil, types: nil, query_options: nil
+        # @example Query using custom timeout and retry policy:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   batch_client = spanner.batch_client "my-instance", "my-database"
+        #   batch_snapshot = batch_client.batch_snapshot
+        #
+        #   timeout = 30.0
+        #   retry_policy = {
+        #     initial_delay: 0.25,
+        #     max_delay:     32.0,
+        #     multiplier:    1.3,
+        #     retry_codes:   ["UNAVAILABLE"]
+        #   }
+        #   call_options = { timeout: timeout, retry_policy: retry_policy }
+        #
+        #   results = batch_snapshot.execute_query \
+        #      "SELECT * FROM users",
+        #      call_options: call_options
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
+        def execute_query sql, params: nil, types: nil, query_options: nil,
+                          call_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
 
           session.execute_query sql, params: params, types: types,
                                 transaction: tx_selector,
-                                query_options: query_options
+                                query_options: query_options,
+                                call_options: call_options
         end
         alias execute execute_query
         alias query execute_query
@@ -578,6 +660,19 @@ 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] 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:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read
         #   operation.
@@ -595,14 +690,16 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
-        def read table, columns, keys: nil, index: nil, limit: nil
+        def read table, columns, keys: nil, index: nil, limit: nil,
+                 call_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
           keys = Convert.to_key_set keys
 
           session.read table, columns, keys: keys, index: index, limit: limit,
-                                       transaction: tx_selector
+                                       transaction: tx_selector,
+                                       call_options: call_options
         end
 
         ##
@@ -663,17 +760,15 @@ module Google
         def self.load data, service: nil, query_options: nil
           data = JSON.parse data, symbolize_names: true unless data.is_a? Hash
 
-          session_grpc = Google::Spanner::V1::Session.decode \
-            Base64.decode64(data[:session])
-          transaction_grpc = Google::Spanner::V1::Transaction.decode \
-            Base64.decode64(data[:transaction])
+          session_grpc = V1::Session.decode Base64.decode64(data[:session])
+          transaction_grpc = V1::Transaction.decode Base64.decode64(data[:transaction])
 
           from_grpc transaction_grpc, Session.from_grpc(session_grpc, service, query_options: query_options)
         end
 
         ##
         # @private Creates a new BatchSnapshot instance from a
-        # Google::Spanner::V1::Transaction.
+        # `Google::Cloud::Spanner::V1::Transaction`.
         def self.from_grpc grpc, session
           new grpc, session
         end
@@ -682,7 +777,7 @@ module Google
 
         # The TransactionSelector to be used for queries
         def tx_selector
-          Google::Spanner::V1::TransactionSelector.new id: transaction_id
+          V1::TransactionSelector.new id: transaction_id
         end
 
         ##
@@ -692,7 +787,7 @@ module Google
           raise "Must have active connection to service" unless session
         end
 
-        def execute_partition_query partition
+        def execute_partition_query partition, call_options: nil
           query_options = partition.execute.query_options
           query_options = query_options.to_h unless query_options.nil?
           session.execute_query \
@@ -701,16 +796,18 @@ module Google
             types: partition.execute.param_types.to_h,
             transaction: partition.execute.transaction,
             partition_token: partition.execute.partition_token,
-            query_options: query_options
+            query_options: query_options,
+            call_options: call_options
         end
 
-        def execute_partition_read partition
+        def execute_partition_read partition, call_options: nil
           session.read partition.read.table,
                        partition.read.columns.to_a,
                        keys: partition.read.key_set,
                        index: partition.read.index,
                        transaction: partition.read.transaction,
-                       partition_token: partition.read.partition_token
+                       partition_token: partition.read.partition_token,
+                       call_options: call_options
         end
       end
     end