google-cloud-bigtable 1.2.2 → 1.3.0

data/lib/google/cloud/bigtable/backup/job.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# 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.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      class Backup
+        ##
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of an backup create operation. The job can
+        # be refreshed to retrieve the backup object once the operation has been completed.
+        #
+        # See {Cluster#create_backup}.
+        #
+        # @see https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.longrunning#google.longrunning.Operation
+        #   Long-running Operation
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #   table = instance.table("my-table")
+        #
+        #   expire_time = Time.now + 60 * 60 * 7
+        #   job = cluster.create_backup(table, "my-backup", expire_time)
+        #
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        class Job < LongrunningJob
+          ##
+          # Get the backup object from operation results.
+          #
+          # @return [Google::Cloud::Bigtable::Backup, nil] The backup instance, or `nil` if the operation is not
+          #   complete.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #   table = instance.table("my-table")
+          #
+          #   expire_time = Time.now + 60 * 60 * 7
+          #   job = cluster.create_backup(table, "my-backup", expire_time)
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          #   if job.error?
+          #     status = job.error
+          #   else
+          #     backup = job.backup
+          #   end
+          #
+          def backup
+            Backup.from_grpc results, service if results
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# 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.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      class Backup
+        ##
+        # 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
+          # Creates a new Backup::List with an array of backups.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of backups.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   backups = cluster.backups
+          #
+          #   if backups.next?
+          #     next_backups = backups.next
+          #   end
+          #
+          def next?
+            grpc.next_page?
+          end
+
+          ##
+          # Retrieves the next page of backups.
+          #
+          # @return [Backup::List] The list of backups.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   backups = cluster.backups
+          #
+          #   if backups.next?
+          #     next_backups = backups.next
+          #   end
+          #
+          def next
+            ensure_grpc!
+
+            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 [Backup] backup The backup object.
+          #
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
+          #
+          # @example Iterating each backup by passing a block:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   cluster.backups.all do |backup|
+          #     puts backup.backup_id
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   instance = bigtable.instance("my-instance")
+          #   cluster = instance.cluster("my-cluster")
+          #
+          #   all_backup_ids = cluster.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 Snapshot::List from a Google::Gax::PagedEnumerable<Google::Bigtable::Admin::V2::Backup> object.
+          # @param grpc [Google::Gax::PagedEnumerable<Google::Bigtable::Admin::V2::Backup> ]
+          # @param service [Google::Cloud::Bigtable::Service]
+          # @return [Array<Google::Cloud::Bigtable::Backup>]
+          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
+
+          # @private
+          #
+          # Raises an error if an active gRPC call is not available.
+          def ensure_grpc!
+            raise "Must have active gRPC call" unless grpc
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/bigtable/cluster.rb

@@ -15,6 +15,7 @@
 # limitations under the License.
 
 
+require "google/cloud/bigtable/backup"
 require "google/cloud/bigtable/cluster/list"
 require "google/cloud/bigtable/cluster/job"
 
@@ -196,6 +197,104 @@ module Google
           @grpc.location
         end
 
+        ##
+        # Creates a new Cloud Bigtable Backup.
+        #
+        # @param source_table [Table, String] The table object, or the name of the table,
+        #   from which the backup is to be created. The table needs to be in the same
+        #   instance as the backup. Required.
+        # @param backup_id [String] The id of the backup to be created. This string must
+        #   be between 1 and 50 characters in length and match the regex
+        #   `[_a-zA-Z0-9][-_.a-zA-Z0-9]*`. Required.
+        # @param expire_time [Time] The expiration time of the backup, with microseconds
+        #     granularity that must be at least 6 hours and at most 30 days
+        #     from the time the request is received. Once the `expire_time`
+        #     has passed, Cloud Bigtable will delete the backup and free the
+        #     resources used by the backup. Required.
+        # @return [Google::Cloud::Bigtable::Backup::Job]
+        #   The job representing the long-running, asynchronous processing of
+        #   a backup create operation.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #   table = instance.table("my-table")
+        #
+        #   expire_time = Time.now + 60 * 60 * 7
+        #   job = cluster.create_backup(table, "my-backup", expire_time)
+        #
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        def create_backup source_table, backup_id, expire_time
+          source_table_id = source_table.respond_to?(:name) ? source_table.name : source_table
+          grpc = service.create_backup instance_id:     instance_id,
+                                       cluster_id:      cluster_id,
+                                       backup_id:       backup_id,
+                                       source_table_id: source_table_id,
+                                       expire_time:     expire_time
+          Backup::Job.from_grpc grpc, service
+        end
+
+        ##
+        # Gets a backup in the cluster.
+        #
+        # @param backup_id [String] The unique ID of the requested backup.
+        #
+        # @return [Google::Cloud::Bigtable::Backup, nil] The backup object, or `nil` if not found in the service.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #
+        #   backup = cluster.backup("my-backup")
+        #
+        #   if backup
+        #     puts backup.backup_id
+        #   end
+        #
+        def backup backup_id
+          grpc = service.get_backup instance_id, cluster_id, backup_id
+          Backup.from_grpc grpc, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+
+        ##
+        # Lists all backups in the cluster.
+        #
+        # @return [Array<Google::Cloud::Bigtable::Backup>] (See {Google::Cloud::Bigtable::Backup::List})
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #
+        #   cluster.backups.all do |backup|
+        #     puts backup.backup_id
+        #   end
+        #
+        def backups
+          grpc = service.list_backups instance_id, cluster_id
+          Backup::List.from_grpc grpc, service
+        end
+
         ##
         # Updates the cluster.
         #

data/lib/google/cloud/bigtable/cluster/list.rb

@@ -109,7 +109,7 @@ module Google
           # @yield [cluster] The block for accessing each cluster.
           # @yieldparam [Cluster] cluster The cluster object.
           #
-          # @return [Enumerator]
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
           #
           # @example Iterating each cluster by passing a block:
           #   require "google/cloud/bigtable"

data/lib/google/cloud/bigtable/column_family_map.rb

@@ -117,7 +117,7 @@ module Google
         # @yieldparam [String] name the column family name.
         # @yieldparam [ColumnFamily] column_family the column family object.
         #
-        # @return [Enumerator]
+        # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
         #
         def each
           return enum_for :each unless block_given?

data/lib/google/cloud/bigtable/instance/list.rb

@@ -106,7 +106,7 @@ module Google
           # @yield [instance] The block for accessing each instance.
           # @yieldparam [Instance] instance The instance object.
           #
-          # @return [Enumerator]
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
           #
           # @example Iterating each instance by passing a block:
           #   require "google/cloud/bigtable"

data/lib/google/cloud/bigtable/longrunning_job.rb

@@ -97,6 +97,17 @@ module Google
           @grpc.wait_until_done!
         end
 
+        ##
+        # @private Gets the metadata object of the operation.
+        #
+        # @return [Object, nil] `nil` if the operation is not complete.
+        #
+        def metadata
+          return nil unless done?
+          return nil unless @grpc.grpc_op.result == :response
+          @grpc.metadata
+        end
+
         # @private
         # New BasicJob from a Google::Gax::Operation object.
         def self.from_grpc grpc, service

data/lib/google/cloud/bigtable/service.rb

@@ -734,6 +734,75 @@ module Google
           end
         end
 
+        ##
+        # Starts creating a new backup. The underlying Google::Longrunning::Operation tracks creation of the backup.
+        #
+        # @return [Google::Gax::Operation]
+        #
+        def create_backup instance_id:, cluster_id:, backup_id:, source_table_id:, expire_time:
+          backup = Google::Bigtable::Admin::V2::Backup.new source_table: table_path(instance_id, source_table_id),
+                                                           expire_time:  expire_time
+          execute do
+            tables.create_backup cluster_path(instance_id, cluster_id), backup_id, backup
+          end
+        end
+
+        ##
+        # @return [Google::Bigtable::Admin::V2::Backup]
+        #
+        def get_backup instance_id, cluster_id, backup_id
+          execute do
+            tables.get_backup backup_path(instance_id, cluster_id, backup_id)
+          end
+        end
+
+        ##
+        # @return [Google::Gax::PagedEnumerable<Google::Bigtable::Admin::V2::Backup>]
+        #
+        def list_backups instance_id, cluster_id
+          execute do
+            tables.list_backups cluster_path(instance_id, cluster_id)
+          end
+        end
+
+        ##
+        # @param backup [Google::Bigtable::Admin::V2::Backup | Hash]
+        # @param fields [Array(String|Symbol)] the paths of fields to be updated
+        #
+        def update_backup backup, fields
+          mask = Google::Protobuf::FieldMask.new paths: fields.map(&:to_s)
+          execute do
+            tables.update_backup backup, mask
+          end
+        end
+
+        def delete_backup instance_id, cluster_id, backup_id
+          execute do
+            tables.delete_backup backup_path(instance_id, cluster_id, backup_id)
+          end
+        end
+
+        ##
+        # Create a new table by restoring from a completed backup.
+        #
+        # @param table_id [String] The table ID for the new table. This table must not yet exist.
+        # @param instance_id [String] The instance ID for the source backup. The table will be created in this instance.
+        # @param cluster_id [String] The cluster ID for the source backup.
+        # @param backup_id [String] The backup ID for the source backup.
+        #
+        # @return [Google::Gax::Operation] The {Google::Longrunning::Operation#metadata metadata} field type is
+        #   {Google::Bigtable::Admin::RestoreTableMetadata RestoreTableMetadata}. The
+        #   {Google::Longrunning::Operation#response response} type is {Google::Bigtable::Admin::V2::Table Table}, if
+        #   successful.
+        #
+        def restore_table table_id, instance_id, cluster_id, backup_id
+          execute do
+            tables.restore_table instance_path(instance_id),
+                                 table_id: table_id,
+                                 backup:   backup_path(instance_id, cluster_id, backup_id)
+          end
+        end
+
         ##
         # Executes the API call and wrap errors to {Google::Cloud::Error}.
         #
@@ -821,6 +890,16 @@ module Google
           Admin::V2::BigtableInstanceAdminClient.app_profile_path project_id, instance_id, app_profile_id
         end
 
+        ##
+        # Creates a formatted backup path.
+        #
+        # @return [String] Formatted backup path
+        #   `projects/<project>/instances/<instance>/clusters/<cluster>/backups/<backup>`
+        #
+        def backup_path instance_id, cluster_id, backup_id
+          Admin::V2::BigtableTableAdminClient.backup_path project_id, instance_id, cluster_id, backup_id
+        end
+
         ##
         # Inspects the service object.
         # @return [String]