google-cloud-bigtable 2.3.0 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ceb71908240117b3c3e98f009a6be24f4ae9ca510523414b91720aab576f925a
-  data.tar.gz: 15c5a7c7617184eac62271c0ba4b2de71b4f9d643c25751dcef0de98dde7d67c
+  metadata.gz: 68dcd0446d6056db7e6f26fbe0d9edea6748e76135ce7cbcc4ec3da4ed7cef28
+  data.tar.gz: fcb5b099fcee71414de91250901a0bf12385311d67731e3dee3265551b3d700d
 SHA512:
-  metadata.gz: 00155edefe171f720de9af636a6a8be2844f889c1750af57a851de83c567e6fc746ce1dbf2f05515d73f0424acade2566874d096f867af1b8c1f5b99e132e81c
-  data.tar.gz: e8a2f9731e9d43897c213ace6810f3a4dcc86a9f5d71eefcf802143c34ca6a151b23e2649081779932c03244e4f3c1ca182f214f122e82b76cbc3a0404d3e54f
+  metadata.gz: cb0a94391f397bac9dea00a4624aa721bc3e891b45a9994908af191f72ac6879bb60a4c0081a02d46437cc7f939eed44a2fe0bc89028f1fc6bcc4fd05dc69d6d
+  data.tar.gz: 3f8762093f07e17140f092c42a0230a92343647bf356858df6a1e04225a89d3b5b0c849478fc53cb917f525b64dad8c0034a83ce65c8de79f900854001f6cc1e

data/AUTHENTICATION.md

@@ -95,7 +95,8 @@ client = Google::Cloud::Bigtable.new
 
 ### Configuration
 
-The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+The **Project ID** and the path to the **Credentials JSON** file can be configured
+instead of placing them in environment variables or providing them as arguments.
 
 ```ruby
 require "google/cloud/bigtable"

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Release History
 
+### 2.6.1 / 2021-07-08
+
+#### Documentation
+
+* Update AUTHENTICATION.md in handwritten packages
+
+### 2.6.0 / 2021-05-03
+
+#### Features
+
+* Add support for Backup restore to different Instance
+  * Add instance to Backup#restore
+
+### 2.5.0 / 2021-04-20
+
+#### Features
+
+* Add CMEK support
+  * Add kms_key to ClusterMap#add
+  * Add Cluster#kms_key
+  * Add EncryptionInfo
+  * Add ClusterState#encryption_infos
+  * Add ENCRYPTION_VIEW support to Table
+  * Update docs in Table::ClusterState
+  * Add Backup#encryption_info
+
+### 2.4.1 / 2021-04-01
+
+#### Bug Fixes
+
+* Update internal management of view states in Table
+
+### 2.4.0 / 2021-03-10
+
+#### Features
+
+* Drop support for Ruby 2.4 and add support for Ruby 3.0
+
+#### Documentation
+
+* Add link to Garbage collection docs
+
 ### 2.3.0 / 2021-02-04
 
 #### Features

data/CONTRIBUTING.md

@@ -24,7 +24,7 @@ be able to accept your pull requests.
 In order to use the google-cloud-bigtable console and run the project's tests,
 there is a small amount of setup:
 
-1. Install Ruby. google-cloud-bigtable requires Ruby 2.4+. You may choose to
+1. Install Ruby. google-cloud-bigtable requires Ruby 2.5+. You may choose to
    manage your Ruby and gem installations with [RVM](https://rvm.io/),
    [rbenv](https://github.com/rbenv/rbenv), or
    [chruby](https://github.com/postmodern/chruby).
@@ -119,15 +119,14 @@ If you alter an example's title, you may encounter breaking tests.
 ### Bigtable Acceptance Tests
 
 The Bigtable acceptance tests interact with the live service API. Follow the
-instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
+instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
 the Bigtable API. Occasionally, some API features may not yet be generally
 available, making it difficult for some contributors to successfully run the
 entire acceptance test suite. However, please ensure that you do successfully
 run acceptance tests for any code areas covered by your pull request.
 
 To run the acceptance tests, first create and configure a project in the Google
-Developers Console, as described in the {file:AUTHENTICATION.md Authentication
-guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
+Developers Console, as described in the {file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
 the KEYFILE location on your system.
 
 Before you can run the Bigtable acceptance tests, you must first create indexes

data/LOGGING.md

@@ -3,7 +3,7 @@
 To enable logging for this library, set the logger for the underlying
 [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
 that you set may be a Ruby stdlib
-[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
+[`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
 shown below, or a
 [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
 that will write logs to [Stackdriver

data/OVERVIEW.md

@@ -396,5 +396,5 @@ instance.delete
 ## Additional information
 
 Google Bigtable can be configured to use an emulator or to enable gRPC's
-logging. To learn more, see the {file:EMULATOR.md Emulator guide} and
+logging. To learn more, see the {file:EMULATOR.md Emulator guide}} and
 {file:LOGGING.md Logging guide}.

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

@@ -122,12 +122,12 @@ module Google
           #     app_profile.name
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless next?
               grpc.next_page
               results = self.class.from_grpc grpc, service

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

@@ -18,10 +18,10 @@
 require "google/cloud/bigtable/backup/job"
 require "google/cloud/bigtable/backup/list"
 require "google/cloud/bigtable/convert"
+require "google/cloud/bigtable/encryption_info"
 require "google/cloud/bigtable/policy"
 require "google/cloud/bigtable/table/restore_job"
 
-
 module Google
   module Cloud
     module Bigtable
@@ -207,6 +207,27 @@ module Google
           state == :READY
         end
 
+        ##
+        # The encryption information for the backup. See also {Instance::ClusterMap#add}.
+        #
+        # @return [Google::Cloud::Bigtable::EncryptionInfo] The encryption information for the backup.
+        #
+        # @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")
+        #
+        #   encryption_info = backup.encryption_info
+        #   encryption_info.encryption_type #=> :GOOGLE_DEFAULT_ENCRYPTION
+        #
+        def encryption_info
+          EncryptionInfo.from_grpc @grpc.encryption_info
+        end
+
         ##
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
         # policy for the backup.
@@ -328,9 +349,12 @@ module Google
         end
 
         ##
-        # Creates a new table by restoring from a completed backup.
+        # Creates a new table by restoring data from a completed backup. The new table may be created in an instance
+        # different than that of the backup.
         #
         # @param table_id [String] The table ID for the new table. This table must not yet exist. Required.
+        # @param instance [Instance, String] The instance or the ID of the instance for the new table, if different from
+        #   the instance of the backup. Optional.
         #
         # @return [Google::Cloud::Bigtable::Table::RestoreJob] The job representing the long-running, asynchronous
         #   processing of a backup restore table operation.
@@ -356,8 +380,35 @@ module Google
         #     optimized = job.optimize_table_operation_name
         #   end
         #
-        def restore table_id
-          grpc = service.restore_table table_id, instance_id, cluster_id, backup_id
+        # @example Create the table in a different instance.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #
+        #   backup = cluster.backup("my-backup")
+        #
+        #   table_instance = bigtable.instance("my-other-instance")
+        #   job = backup.restore("my-new-table", instance: table_instance)
+        #
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     table = job.table
+        #     optimized = job.optimize_table_operation_name
+        #   end
+        #
+        def restore table_id, instance: nil
+          table_instance_id = instance.respond_to?(:instance_id) ? instance.instance_id : instance
+          grpc = service.restore_table table_id,
+                                       instance_id,
+                                       cluster_id,
+                                       backup_id,
+                                       table_instance_id: table_instance_id
           Table::RestoreJob.from_grpc grpc, service
         end
 

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

@@ -124,12 +124,12 @@ module Google
           #     backup.backup_id
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless next?
               grpc.next_page
               results = self.class.from_grpc grpc, service

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

@@ -57,11 +57,12 @@ module Google
 
           raise_if chunk.value_size.positive?, "Commit rows cannot have a non-zero value_size." if chunk.commit_row
 
-          if state == NEW_ROW
+          case state
+          when NEW_ROW
             process_new_row
-          elsif state == CELL_IN_PROGRESS
+          when CELL_IN_PROGRESS
             process_cell_in_progress
-          elsif state == ROW_IN_PROGRESS
+          when ROW_IN_PROGRESS
             process_row_in_progress
           end
         end

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

@@ -168,8 +168,10 @@ module Google
         ##
         # The type of storage used by this cluster to serve its
         # parent instance's tables, unless explicitly overridden.
-        # Valid values are `:SSD`(Flash (SSD) storage should be used),
-        # `:HDD`(Magnetic drive (HDD) storage should be used)
+        # Valid values are:
+        #
+        #   * `:SSD` - Flash (SSD) storage should be used.
+        #   * `:HDD` - Magnetic drive (HDD) storage should be used.
         #
         # @return [Symbol]
         #
@@ -197,6 +199,24 @@ module Google
           @grpc.location
         end
 
+        ##
+        # The full name of the Cloud KMS encryption key for the cluster, if it is CMEK-protected, in the format
+        # `projects/{key_project_id}/locations/{location}/keyRings/{ring_name}/cryptoKeys/{key_name}`.
+        #
+        # The requirements for this key are:
+        #
+        # 1. The Cloud Bigtable service account associated with the project that contains this cluster must be granted
+        #    the `cloudkms.cryptoKeyEncrypterDecrypter` role on the CMEK key.
+        # 2. Only regional keys can be used and the region of the CMEK key must match the region of the cluster.
+        # 3. All clusters within an instance must use the same CMEK key.
+        #
+        # @return [String, nil] The full name of the Cloud KMS encryption key, or `nil` if the cluster is not
+        #   CMEK-protected.
+        #
+        def kms_key
+          @grpc.encryption_config&.kms_key_name
+        end
+
         ##
         # Creates a new Cloud Bigtable Backup.
         #

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

@@ -129,12 +129,12 @@ module Google
           #     puts cluster.cluster_id
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless results.next?
               results = results.next
             end

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

@@ -45,7 +45,11 @@ module Google
         ##
         # The garbage collection rule to be used for the column family.
         # Optional. The service default value will be used when not specified.
+        #
+        # @see https://cloud.google.com/bigtable/docs/garbage-collection Garbage collection
+        #
         # @return [Google::Cloud::Bigtable::GcRule, nil]
+        #
         attr_accessor :gc_rule
 
         # @private

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

@@ -222,6 +222,8 @@ module Google
         ##
         # Updates an existing column family in the table.
         #
+        # @see https://cloud.google.com/bigtable/docs/garbage-collection Garbage collection
+        #
         # @param name [String] Column family name.
         # @param gc_rule [Google::Cloud::Bigtable::GcRule] The new garbage
         #   collection rule to be used for the column family. Optional. The

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Copyright 2021 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/bigtable/status"
+
+module Google
+  module Cloud
+    module Bigtable
+      ##
+      # # EncryptionInfo
+      #
+      # Encryption information for a given resource.
+      #
+      # See {Backup#encryption_info} and {Table::ClusterState#encryption_infos}.
+      #
+      # @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")
+      #
+      #   encryption_info = backup.encryption_info
+      #   encryption_info.encryption_type #=> :GOOGLE_DEFAULT_ENCRYPTION
+      #
+      # @example Retrieve a table with cluster states containing encryption info.
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   table = bigtable.table("my-instance", "my-table", view: :ENCRYPTION_VIEW, perform_lookup: true)
+      #
+      #   table.cluster_states.each do |cs|
+      #     puts cs.cluster_name
+      #     puts cs.encryption_infos.first.encryption_type
+      #   end
+      #
+      class EncryptionInfo
+        # @private
+        #
+        # Creates a new EncryptionInfo instance.
+        def initialize grpc
+          @grpc = grpc
+        end
+
+        ##
+        # The type of encryption used to protect the resource. Possible values:
+        #
+        # * `ENCRYPTION_TYPE_UNSPECIFIED` - Encryption type was not specified, though data at rest remains encrypted.
+        # * `GOOGLE_DEFAULT_ENCRYPTION` - The data backing the resource is encrypted at rest with a key that is
+        #   fully managed by Google. No key version or status will be populated. This is the default state.
+        # * `CUSTOMER_MANAGED_ENCRYPTION` - The data backing the resource is encrypted at rest with a key that is
+        #   managed by the customer. The in-use version of the key and its status are populated for CMEK-protected
+        #   tables. CMEK-protected backups are pinned to the key version that was in use at the time the backup was
+        #   taken. This key version is populated but its status is not tracked and is reported as `UNKNOWN`.
+        #
+        # See also {#encryption_status}, {#kms_key_version} and {Instance::ClusterMap#add}.
+        #
+        # @return [Symbol] The encryption type code as an uppercase symbol.
+        #
+        def encryption_type
+          @grpc.encryption_type
+        end
+
+        ##
+        # The status of encrypt/decrypt calls on underlying data for the resource. Regardless of status, the existing
+        # data is always encrypted at rest.
+        #
+        # See also {#encryption_type}, {#kms_key_version} and {Instance::ClusterMap#add}.
+        #
+        # @return [Google::Cloud::Bigtable::Status, nil] The encryption status object, or `nil` if not present.
+        #
+        def encryption_status
+          status_grpc = @grpc.encryption_status
+          Status.from_grpc status_grpc if status_grpc
+        end
+
+        ##
+        # The version of the Cloud KMS key specified in the parent cluster that is in use for the data underlying the
+        # table.
+        #
+        # See also {#encryption_type}, {#encryption_status} and {Instance::ClusterMap#add}.
+        #
+        # @return [String, nil] The Cloud KMS key version, or `nil` if not present.
+        #
+        def kms_key_version
+          @grpc.kms_key_version unless @grpc.kms_key_version.empty?
+        end
+
+        # @private
+        #
+        # Creates a new EncryptionInfo instance from a Google::Cloud::Bigtable::Admin::V2::EncryptionInfo.
+        #
+        # @param grpc [Google::Cloud::Bigtable::Admin::V2::EncryptionInfo]
+        # @return [Google::Cloud::Bigtable::EncryptionInfo]
+        def self.from_grpc grpc
+          new grpc
+        end
+      end
+    end
+  end
+end

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

@@ -28,6 +28,8 @@ module Google
       # so it is possible for reads to return a cell even if it matches the
       # active GC expression for its column family.
       #
+      # @see https://cloud.google.com/bigtable/docs/garbage-collection Garbage collection
+      #
       # GC Rule types:
       #   * `max_num_versions` - A garbage-collection rule that explicitly
       #     states the maximum number of cells to keep for all columns in a

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

@@ -520,6 +520,7 @@ module Google
         def table table_id, view: nil, perform_lookup: nil, app_profile_id: nil
           ensure_service!
 
+          view ||= :SCHEMA_VIEW
           table = if perform_lookup
                     grpc = service.get_table instance_id, table_id, view: view
                     Table.from_grpc grpc, service, view: view

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

@@ -15,28 +15,31 @@
 # limitations under the License.
 
 
+require "google/cloud/bigtable/admin/v2"
+
 module Google
   module Cloud
     module Bigtable
       class Instance
         ##
-        # Instance::ClusterMap is a hash with cluster ID keys and cluster configuration values.
-        # It is used to create a cluster.
+        # Instance::ClusterMap is a hash with cluster ID keys and cluster configuration values. It is used to create a
+        # cluster.
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
-        #  clusters = Google::Cloud::Bigtable::Instance::ClusterMap.new
+        #   bigtable = Google::Cloud::Bigtable.new
         #
-        #  clusters.add("cluster-1", "us-east1-b", nodes: 3, storage_type: :SSD)
+        #   job = bigtable.create_instance("my-instance") do |clusters|
+        #     clusters.add("test-cluster", "us-east1-b", nodes: 3, storage_type: :SSD)
+        #   end
         #
-        #  # Or
-        #  clusters.add("cluster-2", "us-east1-b")
+        #   job.wait_until_done!
         #
         class ClusterMap < DelegateClass(::Hash)
           # @private
           #
-          # Creates a new Instance::ClusterMap with an hash of Cluster name and
-          # cluster grpc instances.
+          # Creates a new Instance::ClusterMap with an hash of Cluster name and cluster grpc instances.
           def initialize value = {}
             super value
           end
@@ -45,24 +48,61 @@ module Google
           # Adds a cluster to the cluster map.
           #
           # @param name [String] The unique identifier for the cluster.
-          # @param location [String]
-          #   The location where this cluster's nodes and storage reside. For best
-          #   performance, clients should be located as close as possible to this
-          #   cluster. Currently only zones are supported.
-          # @param nodes [Integer] Number of nodes for the cluster. When creating
-          #   an instance of type `:DEVELOPMENT`, `nodes` must not be set.
-          # @param storage_type [Symbol]
-          #   Valid values are:
-          #   * `:SSD`(Flash (SSD) storage should be used),
-          #   *`:HDD`(Magnetic drive (HDD) storage should be used)
+          # @param location [String] The location where this cluster's nodes and storage reside. For best performance,
+          #   clients should be located as close as possible to this cluster. Currently only zones are supported.
+          # @param nodes [Integer] Number of nodes for the cluster. When creating an instance of type `:DEVELOPMENT`,
+          #   `nodes` must not be set.
+          # @param storage_type [Symbol] The type of storage used by this cluster to serve its parent instance's tables,
+          #   unless explicitly overridden. Valid values are:
+          #
+          #   * `:SSD` - Flash (SSD) storage should be used.
+          #   * `:HDD` - Magnetic drive (HDD) storage should be used.
+          #
+          #   If not set then default will set to `:STORAGE_TYPE_UNSPECIFIED`.
+          # @param kms_key [String] The full name of a Cloud KMS encryption key for a CMEK-protected cluster, in the
+          #   format `projects/{key_project_id}/locations/{location}/keyRings/{ring_name}/cryptoKeys/{key_name}`.
+          #
+          #   The requirements for this key are:
+          #
+          #   1. The Cloud Bigtable service account associated with the project that contains this cluster must be
+          #      granted the `cloudkms.cryptoKeyEncrypterDecrypter` role on the CMEK key.
+          #   2. Only regional keys can be used and the region of the CMEK key must match the region of the cluster.
+          #   3. All clusters within an instance must use the same CMEK key.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   job = bigtable.create_instance("my-instance") do |clusters|
+          #     clusters.add("test-cluster", "us-east1-b", nodes: 3, storage_type: :SSD)
+          #   end
+          #
+          #   job.wait_until_done!
+          #
+          # @example With a Cloud KMS encryption key name for a CMEK-protected cluster:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   kms_key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"
+          #   job = bigtable.create_instance("my-instance") do |clusters|
+          #     clusters.add("test-cluster", "us-east1-b", kms_key: kms_key_name)
+          #   end
           #
-          #   If not set then default will set to `:STORAGE_TYPE_UNSPECIFIED`
+          #   job.wait_until_done!
           #
-          def add name, location, nodes: nil, storage_type: nil
+          def add name, location, nodes: nil, storage_type: nil, kms_key: nil
+            if kms_key
+              encryption_config = Google::Cloud::Bigtable::Admin::V2::Cluster::EncryptionConfig.new(
+                kms_key_name: kms_key
+              )
+            end
             attrs = {
               serve_nodes:          nodes,
               location:             location,
-              default_storage_type: storage_type
+              default_storage_type: storage_type,
+              encryption_config:    encryption_config
             }.delete_if { |_, v| v.nil? }
 
             self[name] = Google::Cloud::Bigtable::Admin::V2::Cluster.new attrs

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

@@ -126,12 +126,12 @@ module Google
           #     puts instance.instance_id
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless results.next?
               results = results.next
             end

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

@@ -335,7 +335,8 @@ module Google
         #   end
         #
         class Response
-          attr_reader :index, :status
+          attr_reader :index
+          attr_reader :status
 
           ##
           # @private Creates a MutationEntry::Response object.

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

@@ -54,7 +54,8 @@ module Google
       #   policy.roles["roles/viewer"] = ["allUsers"]
       #
       class Policy
-        attr_reader :etag, :roles
+        attr_reader :etag
+        attr_reader :roles
 
         # Creates a Policy instance.
         # @param etag [String]

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

@@ -316,18 +316,18 @@ module Google
         #
         #   table = bigtable.table("my-instance", "my-table")
         #
-        # @example Get a table with schema-only view.
+        # @example Retrieve a table with a schema-only view.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true, view: :SCHEMA_VIEW)
+        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
         #   if table
         #     puts table.name
         #     puts table.column_families
         #   end
         #
-        # @example Get a table with all fields, cluster states, and column families.
+        # @example Retrieve a table with all fields, cluster states, and column families.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -342,6 +342,7 @@ module Google
         def table instance_id, table_id, view: nil, perform_lookup: nil, app_profile_id: nil
           ensure_service!
 
+          view ||= :SCHEMA_VIEW
           table = if perform_lookup
                     grpc = service.get_table instance_id, table_id, view: view
                     Table.from_grpc grpc, service, view: view

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

@@ -141,7 +141,8 @@ module Google
       #     Default value is false.
       #
       class SingleClusterRouting < RoutingPolicy
-        attr_reader :cluster_id, :allow_transactional_writes
+        attr_reader :cluster_id
+        attr_reader :allow_transactional_writes
 
         ##
         # Creates a new single-cluster routing policy.
@@ -155,6 +156,7 @@ module Google
         #   Default value is false.
         #
         def initialize cluster_id, allow_transactional_writes
+          super()
           @cluster_id = cluster_id
           @allow_transactional_writes = allow_transactional_writes
         end

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

@@ -30,7 +30,11 @@ module Google
         # Row cell built from data chunks.
         #
         class Cell
-          attr_reader :family, :qualifier, :value, :labels, :timestamp
+          attr_reader :family
+          attr_reader :qualifier
+          attr_reader :value
+          attr_reader :labels
+          attr_reader :timestamp
 
           ##
           # Creates a row cell instance.

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

@@ -170,10 +170,10 @@ module Google
         # @return [Boolean]
         #
         def start_key_read? range
-          start_key = if !range.start_key_closed.empty?
-                        range.start_key_closed
-                      else
+          start_key = if range.start_key_closed.empty?
                         range.start_key_open
+                      else
+                        range.start_key_closed
                       end
 
           start_key.empty? || last_key >= start_key
@@ -186,10 +186,10 @@ module Google
         # @return [Boolean]
         #
         def end_key_read? range
-          end_key = if !range.end_key_closed.empty?
-                      range.end_key_closed
-                    else
+          end_key = if range.end_key_closed.empty?
                       range.end_key_open
+                    else
+                      range.end_key_closed
                     end
 
           end_key && end_key <= last_key

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

@@ -752,17 +752,20 @@ module Google
         # 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 instance_id [String] The instance ID for the source backup. The table will be created in this instance
+        #   if table_instance_id is not provided.
         # @param cluster_id [String] The cluster ID for the source backup.
         # @param backup_id [String] The backup ID for the source backup.
+        # @param table_instance_id [String] The instance ID for the table, if different from instance_id. Optional.
         #
         # @return [Gapic::Operation] The {Google::Longrunning::Operation#metadata metadata} field type is
         #   {Google::Cloud::Bigtable::Admin::RestoreTableMetadata RestoreTableMetadata}. The
         #   {Google::Longrunning::Operation#response response} type is
         #   {Google::Cloud::Bigtable::Admin::V2::Table Table}, if successful.
         #
-        def restore_table table_id, instance_id, cluster_id, backup_id
-          tables.restore_table parent:   instance_path(instance_id),
+        def restore_table table_id, instance_id, cluster_id, backup_id, table_instance_id: nil
+          table_instance_id ||= instance_id
+          tables.restore_table parent:   instance_path(table_instance_id),
                                table_id: table_id,
                                backup:   backup_path(instance_id, cluster_id, backup_id)
         end

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

@@ -47,7 +47,10 @@ module Google
       #   end
       #
       class Status
-        attr_reader :code, :description, :message, :details
+        attr_reader :code
+        attr_reader :description
+        attr_reader :message
+        attr_reader :details
 
         ##
         # @private Creates a Status object.

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

@@ -56,6 +56,14 @@ module Google
         # The gRPC Service object.
         attr_accessor :service
 
+        # @private
+        # The current gRPC resource, for testing only.
+        attr_accessor :grpc
+
+        # @private
+        # The current loaded_views, for testing only. See #check_view_and_load, below.
+        attr_reader :loaded_views
+
         ##
         # @return [String] App profile ID for request routing.
         #
@@ -64,10 +72,11 @@ module Google
         # @private
         #
         # Creates a new Table instance.
-        def initialize grpc, service, view: nil
+        def initialize grpc, service, view:
           @grpc = grpc
           @service = service
-          @view = view || :SCHEMA_VIEW
+          raise ArgumentError, "view must not be nil" if view.nil?
+          @loaded_views = Set[view]
         end
 
         ##
@@ -109,7 +118,8 @@ module Google
         end
 
         ##
-        # Reloads table data.
+        # Reloads table data with the provided `view`, or with `SCHEMA_VIEW`
+        # if none is provided. Previously loaded data is not retained.
         #
         # @param view [Symbol] Table view type.
         #   Default view type is `:SCHEMA_VIEW`.
@@ -123,22 +133,41 @@ module Google
         # @return [Google::Cloud::Bigtable::Table]
         #
         def reload! view: nil
-          @view = view || :SCHEMA_VIEW
+          view ||= :SCHEMA_VIEW
           @grpc = service.get_table instance_id, name, view: view
+          @loaded_views = Set[view]
           self
         end
 
         ##
-        # Map from cluster ID to per-cluster table state.
+        # Returns an array of {Table::ClusterState} objects that map cluster ID
+        # to per-cluster table state.
+        #
         # If it could not be determined whether or not the table has data in a
         # particular cluster (for example, if its zone is unavailable), then
-        # there will be an entry for the cluster with UNKNOWN `replication_status`.
-        # Views: `FULL`.
+        # the cluster state's `replication_state` will be `UNKNOWN`.
+        #
+        # Reloads the table with the `FULL` view type to retrieve the cluster states
+        # data, unless the table was previously loaded with view type `ENCRYPTION_VIEW`,
+        # `REPLICATION_VIEW` or `FULL`.
         #
         # @return [Array<Google::Cloud::Bigtable::Table::ClusterState>]
         #
+        # @example Retrieve a table with cluster states.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table", view: :FULL, perform_lookup: true)
+        #
+        #   table.cluster_states.each do |cs|
+        #     puts cs.cluster_name
+        #     puts cs.replication_state
+        #     puts cs.encryption_infos.first.encryption_type
+        #   end
+        #
         def cluster_states
-          check_view_and_load :REPLICATION_VIEW
+          check_view_and_load :FULL, skip_if: [:ENCRYPTION_VIEW, :REPLICATION_VIEW]
           @grpc.cluster_states.map do |name, state_grpc|
             ClusterState.from_grpc state_grpc, name
           end
@@ -146,15 +175,19 @@ module Google
 
         ##
         # Returns a frozen object containing the column families configured for
-        # the table, mapped by column family name. Reloads the table if
-        # necessary to retrieve the column families data, since it is only
-        # available in a table with view type `SCHEMA_VIEW` or `FULL`.
+        # the table, mapped by column family name.
+        #
+        # Reloads the table if necessary to retrieve the column families data,
+        # since it is only available in a table with view type `SCHEMA_VIEW`
+        # or `FULL`. Previously loaded data is retained.
         #
         # Also accepts a block for making modifications to the table's column
         # families. After the modifications are completed, the table will be
         # updated with the changes, and the updated column families will be
         # returned.
         #
+        # @see https://cloud.google.com/bigtable/docs/garbage-collection Garbage collection
+        #
         # @yield [column_families] A block for modifying the table's column
         #   families. Applies multiple column modifications. Performs a series
         #   of column family modifications on the specified table. Either all or
@@ -222,7 +255,10 @@ module Google
         # The granularity (e.g. `MILLIS`, `MICROS`) at which timestamps are stored in
         # this table. Timestamps not matching the granularity will be rejected.
         # If unspecified at creation time, the value will be set to `MILLIS`.
-        # Views: `SCHEMA_VIEW`, `FULL`.
+        #
+        # Reloads the table if necessary to retrieve the column families data,
+        # since it is only available in a table with view type `SCHEMA_VIEW`
+        # or `FULL`. Previously loaded data is retained.
         #
         # @return [Symbol]
         #
@@ -437,7 +473,7 @@ module Google
           }.delete_if { |_, v| v.nil? })
 
           grpc = service.create_table instance_id, table_id, table, initial_splits: initial_splits
-          from_grpc grpc, service
+          from_grpc grpc, service, view: :SCHEMA_VIEW
         end
 
         ##
@@ -623,7 +659,7 @@ module Google
         # @param view [Symbol] View type.
         # @return [Google::Cloud::Bigtable::Table]
         #
-        def self.from_grpc grpc, service, view: nil
+        def self.from_grpc grpc, service, view:
           new grpc, service, view: view
         end
 
@@ -653,20 +689,24 @@ module Google
 
         FIELDS_BY_VIEW = {
           SCHEMA_VIEW:      ["granularity", "column_families"],
+          ENCRYPTION_VIEW:  ["cluster_states"],
           REPLICATION_VIEW: ["cluster_states"],
           FULL:             ["granularity", "column_families", "cluster_states"]
         }.freeze
 
         # @private
         #
-        # Checks and reloads table with expected view and sets fields.
-        # @param view [Symbol] Expected view type.
+        # Checks and reloads table with expected view. Performs additive updates to fields specified by the given view.
+        # @param view [Symbol] The view type to load. If already loaded, no load is performed.
+        # @param skip_if [Symbol] Additional satisfying view types. If already loaded, no load is performed.
         #
-        def check_view_and_load view
+        def check_view_and_load view, skip_if: nil
           ensure_service!
-          @loaded_views ||= Set.new [@view]
 
-          return if @loaded_views.include?(view) || @loaded_views.include?(:FULL)
+          skip = Set.new skip_if
+          skip << view
+          skip << :FULL
+          return if (@loaded_views & skip).any?
 
           grpc = service.get_table instance_id, table_id, view: view
           @loaded_views << view
@@ -674,6 +714,9 @@ module Google
           FIELDS_BY_VIEW[view].each do |field|
             case grpc[field]
             when Google::Protobuf::Map
+              # Special handling for column_families:
+              # Replace contents of existing Map since setting the new Map won't work.
+              # See https://github.com/protocolbuffers/protobuf/issues/4969
               @grpc[field].clear
               grpc[field].each { |k, v| @grpc[field][k] = v }
             else

data/lib/google/cloud/bigtable/table/cluster_state.rb

@@ -15,6 +15,8 @@
 # limitations under the License.
 
 
+require "google/cloud/bigtable/encryption_info"
+
 module Google
   module Cloud
     module Bigtable
@@ -23,6 +25,20 @@ module Google
         # Table::ClusterState is the state of a table's data in a particular cluster.
         #
         # @attr [String] cluster_name The name of the cluster.
+        #
+        # @example Retrieve a table with cluster states.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table", view: :FULL, perform_lookup: true)
+        #
+        #   table.cluster_states.each do |cs|
+        #     puts cs.cluster_name
+        #     puts cs.replication_state
+        #     puts cs.encryption_infos.first.encryption_type
+        #   end
+        #
         class ClusterState
           attr_reader :cluster_name
 
@@ -36,7 +52,7 @@ module Google
 
           ##
           # The state of replication for the table in this cluster.
-          #   Valid values are:
+          #   Valid values include:
           #   * `:INITIALIZING` - The cluster was recently created.
           #   * `:PLANNED_MAINTENANCE` - The table is temporarily unable to serve.
           #   * `:UNPLANNED_MAINTENANCE` - The table is temporarily unable to serve.
@@ -45,6 +61,10 @@ module Google
           #     after a restore, and is being optimized for performance. When
           #     optimizations are complete, the table will transition to `READY`
           #     state.
+          #   * `:STATE_NOT_KNOWN` - If replication state is not present in the object
+          #      because the table view is not `REPLICATION_VIEW` or `FULL`.
+          #   * `:UNKNOWN` - If it could not be determined whether or not the table
+          #     has data in a particular cluster (for example, if its zone is unavailable.)
           #
           # @return [Symbol] The state of replication.
           #
@@ -57,7 +77,8 @@ module Google
           # over pre-existing data from other clusters before it can begin
           # receiving live replication updates and serving.
           #
-          # @return [Boolean] `true` if the table in this cluster is initializing.
+          # @return [Boolean] `true` if the value of {#replication_state} is `INITIALIZING`,
+          #   `false` otherwise.
           #
           def initializing?
             replication_state == :INITIALIZING
@@ -67,8 +88,8 @@ module Google
           # The table is temporarily unable to serve
           # requests from this cluster due to planned internal maintenance.
           #
-          # @return [Boolean] `true` if the table in this cluster is in planned
-          #   maintenance.
+          # @return [Boolean] `true` if the value of {#replication_state} is `PLANNED_MAINTENANCE`,
+          #   `false` otherwise.
           #
           def planned_maintenance?
             replication_state == :PLANNED_MAINTENANCE
@@ -78,8 +99,8 @@ module Google
           # The table is temporarily unable to serve requests from this
           # cluster due to unplanned or emergency maintenance.
           #
-          # @return [Boolean] `true` if the table in this cluster is in unplanned
-          #   maintenance.
+          # @return [Boolean] `true` if the value of {#replication_state} is `UNPLANNED_MAINTENANCE`,
+          #   `false` otherwise.
           #
           def unplanned_maintenance?
             replication_state == :UNPLANNED_MAINTENANCE
@@ -90,7 +111,8 @@ module Google
           # Depending on replication delay, reads may not immediately
           # reflect the state of the table in other clusters.
           #
-          # @return [Boolean] `true` if the table in this cluster is ready.
+          # @return [Boolean] `true` if the value of {#replication_state} is `READY`,
+          #   `false` otherwise.
           #
           def ready?
             replication_state == :READY
@@ -102,13 +124,25 @@ module Google
           # optimizations are complete, the table will transition to `READY`
           # state.
           #
-          # @return [Boolean] `true` if the table in this cluster is being
-          #   optimized.
+          # @return [Boolean] `true` if the value of {#replication_state} is `READY_OPTIMIZING`,
+          #   `false` otherwise.
           #
           def ready_optimizing?
             replication_state == :READY_OPTIMIZING
           end
 
+          ##
+          # The encryption info value objects for the table in this cluster. The encryption info
+          # is only present when the table view is `ENCRYPTION_VIEW` or `FULL`. See also
+          # {Instance::ClusterMap#add}.
+          #
+          # @return [Array<Google::Cloud::Bigtable::EncryptionInfo>] The array of encryption info
+          #   value objects, or an empty array if none are present.
+          #
+          def encryption_infos
+            @grpc.encryption_info.map { |ei_grpc| Google::Cloud::Bigtable::EncryptionInfo.from_grpc ei_grpc }
+          end
+
           # @private
           # New Table::ClusterState from a Google::Cloud::Bigtable::Admin::V2::Table::ClusterState object.
           # @param grpc [Google::Cloud::Bigtable::Admin::V2::Table::ClusterState]

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

@@ -114,12 +114,12 @@ module Google
           #     puts table.table_id
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless next?
               grpc.next_page
               results = self.class.from_grpc grpc, service

data/lib/google/cloud/bigtable/table/restore_job.rb

@@ -108,7 +108,7 @@ module Google
           #   end
           #
           def table
-            Table.from_grpc results, service if results
+            Table.from_grpc results, service, view: :NAME_ONLY if results
           end
         end
       end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Bigtable
-      VERSION = "2.3.0".freeze
+      VERSION = "2.6.1".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-bigtable
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.6.1
 platform: ruby
 authors:
 - Google LLC
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-04 00:00:00.000000000 Z
+date: 2021-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-bigtable-admin-v2
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.24.0
+        version: 1.25.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.24.0
+        version: 1.25.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -197,6 +197,7 @@ files:
 - lib/google/cloud/bigtable/column_range.rb
 - lib/google/cloud/bigtable/convert.rb
 - lib/google/cloud/bigtable/credentials.rb
+- lib/google/cloud/bigtable/encryption_info.rb
 - lib/google/cloud/bigtable/errors.rb
 - lib/google/cloud/bigtable/gc_rule.rb
 - lib/google/cloud/bigtable/instance.rb
@@ -241,14 +242,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.6
+rubygems_version: 3.2.17
 signing_key: 
 specification_version: 4
 summary: API Client library for Cloud Bigtable API