google-cloud-spanner 1.14.0 → 2.0.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

@@ -65,11 +65,13 @@ module Google
       class BatchClient
         ##
         # @private Creates a new Spanner BatchClient instance.
-        def initialize project, instance_id, database_id, session_labels: nil
+        def initialize project, instance_id, database_id, session_labels: nil,
+                       query_options: nil
           @project = project
           @instance_id = instance_id
           @database_id = database_id
           @session_labels = session_labels
+          @query_options = query_options
         end
 
         # The unique identifier for the project.
@@ -231,7 +233,7 @@ module Google
         def load_batch_snapshot serialized_snapshot
           ensure_service!
 
-          BatchSnapshot.load serialized_snapshot, service: @project.service
+          BatchSnapshot.load serialized_snapshot, service: @project.service, query_options: @query_options
         end
 
         ##
@@ -405,11 +407,11 @@ 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
+          Session.from_grpc grpc, @project.service, query_options: @query_options
         end
 
         ##