google-cloud-spanner 1.15.0 → 1.16.0

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

@@ -0,0 +1,177 @@
+# 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
+        class Job
+          ##
+          # # List
+          #
+          # List is a special case Array with additional values for backup
+          # operations.
+          #
+          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::Job::List with an array of
+            # Google::Lognrunning::Operation instances.
+            def initialize arr = []
+              super arr
+            end
+
+            ##
+            # Whether there is a next page of backup jobs.
+            #
+            # @return [Boolean]
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #
+            #   jobs = instance.backup_operations
+            #   if jobs.next?
+            #     next_jobs = jobs.next
+            #   end
+            #
+            def next?
+              grpc.next_page?
+            end
+
+            ##
+            # Retrieve the next page of backup jobs.
+            #
+            # @return [Backup::Job::List]
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #
+            #   jobs = instance.backup_operations
+            #   if jobs.next?
+            #     next_jobs = jobs.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 [job] The block for accessing each backup job.
+            # @yieldparam [Google::Cloud::Spanner::Backup::Job] job The backup
+            #   job object.
+            #
+            # @return [Enumerator]
+            #
+            # @example Iterating each backup job by passing a block:
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #
+            #   jobs = instance.backup_operations
+            #   jobs.all do |job|
+            #     puts job.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"
+            #
+            #   jobs = instance.backup_operations
+            #   all_backup_ids = jobs.all.map do |job|
+            #     job.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::Job::List from a
+            # Google::Gax::PagedEnumerable<Google::Longrunning::Operation>
+            # object. Operation object is a backup operation.
+            #
+            def self.from_grpc grpc, service
+              operations_client = \
+                service.databases.instance_variable_get "@operations_client"
+              jobs = new(Array(grpc.response.operations).map do |job_grpc|
+                Job.from_grpc \
+                  Google::Gax::Operation.new(job_grpc, operations_client),
+                  service
+              end)
+              jobs.grpc = grpc
+              jobs.service = service
+              jobs
+            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
+end

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

@@ -0,0 +1,170 @@
+# 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
+          # Google::Gax::PagedEnumerable<Google::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 Google::Gax::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 Google::Gax::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