google-cloud-bigtable 1.2.0 → 2.1.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 Gapic::PagedEnumerable<Google::Cloud::Bigtable::Admin::V2::Backup> object.
+          # @param grpc [Gapic::PagedEnumerable<Google::Cloud::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/chunk_processor.rb

@@ -49,7 +49,7 @@ module Google
         ##
         # Process chunk and build full row with cells
         #
-        # @param chunk [Google::Bigtable::V2::ReadRowsResponse::CellChunk]
+        # @param chunk [Google::Cloud::Bigtable::V2::ReadRowsResponse::CellChunk]
         #
         def process chunk
           self.chunk = chunk

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.
         #
@@ -267,9 +366,9 @@ module Google
         # @private
         #
         # Creates a new Cluster instance from a
-        # Google::Bigtable::Admin::V2::Cluster.
+        # Google::Cloud::Bigtable::Admin::V2::Cluster.
         #
-        # @param grpc [Google::Bigtable::Admin::V2::Cluster]
+        # @param grpc [Google::Cloud::Bigtable::Admin::V2::Cluster]
         # @param service [Google::Cloud::Bigtable::Service]
         # @return [Google::Cloud::Bigtable::Cluster]
         def self.from_grpc grpc, service

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"
@@ -142,7 +142,7 @@ module Google
 
           # @private
           #
-          # New Cluster::List from a Google::Bigtable::Admin::V2::ListClustersResponse object.
+          # New Cluster::List from a Google::Cloud::Bigtable::Admin::V2::ListClustersResponse object.
           def self.from_grpc grpc, service, instance_id: nil
             clusters = List.new(Array(grpc.clusters).map do |cluster|
               Cluster.from_grpc cluster, service

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

@@ -56,9 +56,9 @@ module Google
 
         # @private
         #
-        # Create a new ColumnFamily instance from a {Google::Bigtable::Admin::V2::ColumnFamily}.
+        # Create a new ColumnFamily instance from a {Google::Cloud::Bigtable::Admin::V2::ColumnFamily}.
         #
-        # @param grpc [Google::Bigtable::Admin::V2::ColumnFamily]
+        # @param grpc [Google::Cloud::Bigtable::Admin::V2::ColumnFamily]
         # @param name [String] Column family name
         # @return [Google::Cloud::Bigtable::ColumnFamily]
         #

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?
@@ -211,7 +211,7 @@ module Google
             warn "The positional gc_rule argument is deprecated. Use the named gc_rule argument instead."
           end
 
-          column_family = Google::Bigtable::Admin::V2::ColumnFamily.new
+          column_family = Google::Cloud::Bigtable::Admin::V2::ColumnFamily.new
           column_family.gc_rule = gc_rule.to_grpc if gc_rule
           @column_families[name] = column_family
 
@@ -248,7 +248,7 @@ module Google
         def update name, gc_rule: nil
           raise ArgumentError, "column family #{name.inspect} does not exist" unless @column_families.has_key? name
 
-          column_family = Google::Bigtable::Admin::V2::ColumnFamily.new
+          column_family = Google::Cloud::Bigtable::Admin::V2::ColumnFamily.new
           column_family.gc_rule = gc_rule.to_grpc if gc_rule
           @column_families[name] = column_family
 
@@ -299,7 +299,7 @@ module Google
         #
         # @param comparison_map [Google::Protobuf::Map] The map to compare the
         #   current map against for building the modification entries.
-        # @return [Array<Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
+        # @return [Array<Google::Cloud::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
         #
         def modifications comparison_map = nil
           comparison_map ||= empty_map
@@ -352,7 +352,7 @@ module Google
         ##
         # Create an empty Google::Protobuf::Map suitable for column_families.
         def empty_map
-          Google::Bigtable::Admin::V2::Table.new.column_families
+          Google::Cloud::Bigtable::Admin::V2::Table.new.column_families
         end
 
         ##
@@ -362,13 +362,13 @@ module Google
         #
         # @param comparison_map [Google::Protobuf::Map] The map to compare the
         #   current map against for building the modification entries.
-        # @return [Array<Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
+        # @return [Array<Google::Cloud::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
         #
         def created_modifications comparison_map
           added_keys = @column_families.keys - comparison_map.keys
 
           added_keys.map do |name|
-            Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest:: \
+            Google::Cloud::Bigtable::Admin::V2::ModifyColumnFamiliesRequest:: \
             Modification.new(
               id:     name,
               create: @column_families[name]
@@ -383,7 +383,7 @@ module Google
         #
         # @param comparison_map [Google::Protobuf::Map] The map to compare the
         #   current map against for building the modification entries.
-        # @return [Array<Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
+        # @return [Array<Google::Cloud::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
         #
         def updated_modifications comparison_map
           possibly_updated_keys = @column_families.keys & comparison_map.keys
@@ -392,7 +392,7 @@ module Google
           end
 
           updated_keys.map do |name|
-            Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest:: \
+            Google::Cloud::Bigtable::Admin::V2::ModifyColumnFamiliesRequest:: \
             Modification.new(
               id:     name,
               update: @column_families[name]
@@ -407,13 +407,13 @@ module Google
         #
         # @param comparison_map [Google::Protobuf::Map] The map to compare the
         #   current map against for building the modification entries.
-        # @return [Array<Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
+        # @return [Array<Google::Cloud::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification>]
         #
         def dropped_modifications comparison_map
           dropped_keys = comparison_map.keys - @column_families.keys
 
           dropped_keys.map do |name|
-            Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest:: \
+            Google::Cloud::Bigtable::Admin::V2::ModifyColumnFamiliesRequest:: \
             Modification.new(
               id:   name,
               drop: true