google-cloud-bigtable 1.0.2 → 1.3.0

data/lib/google/cloud/bigtable/admin/v2/doc/google/bigtable/admin/v2/instance.rb

@@ -19,16 +19,15 @@ module Google
       module V2
         # A collection of Bigtable {Google::Bigtable::Admin::V2::Table Tables} and
         # the resources that serve them.
-        # All tables in an instance are served from a single
-        # {Google::Bigtable::Admin::V2::Cluster Cluster}.
+        # All tables in an instance are served from all
+        # {Google::Bigtable::Admin::V2::Cluster Clusters} in the instance.
         # @!attribute [rw] name
         #   @return [String]
-        #     (`OutputOnly`)
         #     The unique name of the instance. Values are of the form
-        #     `projects/<project>/instances/[a-z][a-z0-9\\-]+[a-z0-9]`.
+        #     `projects/{project}/instances/[a-z][a-z0-9\\-]+[a-z0-9]`.
         # @!attribute [rw] display_name
         #   @return [String]
-        #     The descriptive name for this instance as it appears in UIs.
+        #     Required. The descriptive name for this instance as it appears in UIs.
         #     Can be changed at any time, but should be kept globally unique
         #     to avoid confusion.
         # @!attribute [rw] state
@@ -93,24 +92,22 @@ module Google
         # {Google::Bigtable::Admin::V2::Instance Instance}.
         # @!attribute [rw] name
         #   @return [String]
-        #     (`OutputOnly`)
         #     The unique name of the cluster. Values are of the form
-        #     `projects/<project>/instances/<instance>/clusters/[a-z][-a-z0-9]*`.
+        #     `projects/{project}/instances/{instance}/clusters/[a-z][-a-z0-9]*`.
         # @!attribute [rw] location
         #   @return [String]
         #     (`CreationOnly`)
         #     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, so values should be of the
-        #     form `projects/<project>/locations/<zone>`.
+        #     form `projects/{project}/locations/{zone}`.
         # @!attribute [rw] state
         #   @return [Google::Bigtable::Admin::V2::Cluster::State]
-        #     (`OutputOnly`)
         #     The current state of the cluster.
         # @!attribute [rw] serve_nodes
         #   @return [Integer]
-        #     The number of nodes allocated to this cluster. More nodes enable higher
-        #     throughput and more consistent performance.
+        #     Required. The number of nodes allocated to this cluster. More nodes enable
+        #     higher throughput and more consistent performance.
         # @!attribute [rw] default_storage_type
         #   @return [Google::Bigtable::Admin::V2::StorageType]
         #     (`CreationOnly`)
@@ -165,19 +162,20 @@ module Google
         #     Optional long form description of the use case for this AppProfile.
         # @!attribute [rw] multi_cluster_routing_use_any
         #   @return [Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
-        #     Use a multi-cluster routing policy that may pick any cluster.
+        #     Use a multi-cluster routing policy.
         # @!attribute [rw] single_cluster_routing
         #   @return [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting]
         #     Use a single-cluster routing policy.
         class AppProfile
-          # Read/write requests may be routed to any cluster in the instance, and will
-          # fail over to another cluster in the event of transient errors or delays.
-          # Choosing this option sacrifices read-your-writes consistency to improve
-          # availability.
+          # Read/write requests are routed to the nearest cluster in the instance, and
+          # will fail over to the nearest cluster that is available in the event of
+          # transient errors or delays. Clusters in a region are considered
+          # equidistant. Choosing this option sacrifices read-your-writes consistency
+          # to improve availability.
           class MultiClusterRoutingUseAny; end
 
           # Unconditionally routes all read/write requests to a specific cluster.
-          # This option preserves read-your-writes consistency, but does not improve
+          # This option preserves read-your-writes consistency but does not improve
           # availability.
           # @!attribute [rw] cluster_id
           #   @return [String]

data/lib/google/cloud/bigtable/admin/v2/doc/google/bigtable/admin/v2/table.rb

@@ -17,18 +17,26 @@ module Google
   module Bigtable
     module Admin
       module V2
+        # Information about a table restore.
+        # @!attribute [rw] source_type
+        #   @return [Google::Bigtable::Admin::V2::RestoreSourceType]
+        #     The type of the restore source.
+        # @!attribute [rw] backup_info
+        #   @return [Google::Bigtable::Admin::V2::BackupInfo]
+        #     Information about the backup used to restore the table. The backup
+        #     may no longer exist.
+        class RestoreInfo; end
+
         # A collection of user data indexed by row, column, and timestamp.
         # Each table is served using the resources of its parent cluster.
         # @!attribute [rw] name
         #   @return [String]
-        #     (`OutputOnly`)
-        #     The unique name of the table. Values are of the form
+        #     Output only. The unique name of the table. Values are of the form
         #     `projects/<project>/instances/<instance>/tables/[_a-zA-Z0-9][-_.a-zA-Z0-9]*`.
         #     Views: `NAME_ONLY`, `SCHEMA_VIEW`, `REPLICATION_VIEW`, `FULL`
         # @!attribute [rw] cluster_states
         #   @return [Hash{String => Google::Bigtable::Admin::V2::Table::ClusterState}]
-        #     (`OutputOnly`)
-        #     Map from cluster ID to per-cluster table state.
+        #     Output only. Map from 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`.
@@ -44,13 +52,16 @@ module Google
         #     The granularity (i.e. `MILLIS`) 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`
+        #     Views: `SCHEMA_VIEW`, `FULL`.
+        # @!attribute [rw] restore_info
+        #   @return [Google::Bigtable::Admin::V2::RestoreInfo]
+        #     Output only. If this table was restored from another data source (e.g. a
+        #     backup), this field will be populated with information about the restore.
         class Table
           # The state of a table's data in a particular cluster.
           # @!attribute [rw] replication_state
           #   @return [Google::Bigtable::Admin::V2::Table::ClusterState::ReplicationState]
-          #     (`OutputOnly`)
-          #     The state of replication for the table in this cluster.
+          #     Output only. The state of replication for the table in this cluster.
           class ClusterState
             # Table replication states.
             module ReplicationState
@@ -74,6 +85,11 @@ module Google
               # replication delay, reads may not immediately reflect the state of the
               # table in other clusters.
               READY = 4
+
+              # The table is fully created and ready for use after a restore, and is
+              # being optimized for performance. When optimizations are complete, the
+              # table will transition to `READY` state.
+              READY_OPTIMIZING = 5
             end
           end
 
@@ -99,8 +115,8 @@ module Google
             # Only populates `name` and fields related to the table's schema.
             SCHEMA_VIEW = 2
 
-            # Only populates `name` and fields related to the table's
-            # replication state.
+            # Only populates `name` and fields related to the table's replication
+            # state.
             REPLICATION_VIEW = 3
 
             # Populates all fields.
@@ -157,38 +173,32 @@ module Google
         # for production use. It is not subject to any SLA or deprecation policy.
         # @!attribute [rw] name
         #   @return [String]
-        #     (`OutputOnly`)
-        #     The unique name of the snapshot.
+        #     Output only. The unique name of the snapshot.
         #     Values are of the form
         #     `projects/<project>/instances/<instance>/clusters/<cluster>/snapshots/<snapshot>`.
         # @!attribute [rw] source_table
         #   @return [Google::Bigtable::Admin::V2::Table]
-        #     (`OutputOnly`)
-        #     The source table at the time the snapshot was taken.
+        #     Output only. The source table at the time the snapshot was taken.
         # @!attribute [rw] data_size_bytes
         #   @return [Integer]
-        #     (`OutputOnly`)
-        #     The size of the data in the source table at the time the snapshot was
-        #     taken. In some cases, this value may be computed asynchronously via a
-        #     background process and a placeholder of 0 will be used in the meantime.
+        #     Output only. The size of the data in the source table at the time the
+        #     snapshot was taken. In some cases, this value may be computed
+        #     asynchronously via a background process and a placeholder of 0 will be used
+        #     in the meantime.
         # @!attribute [rw] create_time
         #   @return [Google::Protobuf::Timestamp]
-        #     (`OutputOnly`)
-        #     The time when the snapshot is created.
+        #     Output only. The time when the snapshot is created.
         # @!attribute [rw] delete_time
         #   @return [Google::Protobuf::Timestamp]
-        #     (`OutputOnly`)
-        #     The time when the snapshot will be deleted. The maximum amount of time a
-        #     snapshot can stay active is 365 days. If 'ttl' is not specified,
+        #     Output only. The time when the snapshot will be deleted. The maximum amount
+        #     of time a snapshot can stay active is 365 days. If 'ttl' is not specified,
         #     the default maximum of 365 days will be used.
         # @!attribute [rw] state
         #   @return [Google::Bigtable::Admin::V2::Snapshot::State]
-        #     (`OutputOnly`)
-        #     The current state of the snapshot.
+        #     Output only. The current state of the snapshot.
         # @!attribute [rw] description
         #   @return [String]
-        #     (`OutputOnly`)
-        #     Description of the snapshot.
+        #     Output only. Description of the snapshot.
         class Snapshot
           # Possible states of a snapshot.
           module State
@@ -204,6 +214,89 @@ module Google
             CREATING = 2
           end
         end
+
+        # A backup of a Cloud Bigtable table.
+        # @!attribute [rw] name
+        #   @return [String]
+        #     Output only. A globally unique identifier for the backup which cannot be
+        #     changed. Values are of the form
+        #     `projects/{project}/instances/{instance}/clusters/{cluster}/
+        #        backups/[_a-zA-Z0-9][-_.a-zA-Z0-9]*`
+        #     The final segment of the name must be between 1 and 50 characters
+        #     in length.
+        #
+        #     The backup is stored in the cluster identified by the prefix of the backup
+        #     name of the form
+        #     `projects/{project}/instances/{instance}/clusters/{cluster}`.
+        # @!attribute [rw] source_table
+        #   @return [String]
+        #     Required. Immutable. Name of the table from which this backup was created.
+        #     This needs to be in the same instance as the backup. Values are of the form
+        #     `projects/{project}/instances/{instance}/tables/{source_table}`.
+        # @!attribute [rw] expire_time
+        #   @return [Google::Protobuf::Timestamp]
+        #     Required. 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.
+        # @!attribute [rw] start_time
+        #   @return [Google::Protobuf::Timestamp]
+        #     Output only. `start_time` is the time that the backup was started
+        #     (i.e. approximately the time the
+        #     {Google::Bigtable::Admin::V2::BigtableTableAdmin::CreateBackup CreateBackup}
+        #     request is received).  The row data in this backup will be no older than
+        #     this timestamp.
+        # @!attribute [rw] end_time
+        #   @return [Google::Protobuf::Timestamp]
+        #     Output only. `end_time` is the time that the backup was finished. The row
+        #     data in the backup will be no newer than this timestamp.
+        # @!attribute [rw] size_bytes
+        #   @return [Integer]
+        #     Output only. Size of the backup in bytes.
+        # @!attribute [rw] state
+        #   @return [Google::Bigtable::Admin::V2::Backup::State]
+        #     Output only. The current state of the backup.
+        class Backup
+          # Indicates the current state of the backup.
+          module State
+            # Not specified.
+            STATE_UNSPECIFIED = 0
+
+            # The pending backup is still being created. Operations on the
+            # backup may fail with `FAILED_PRECONDITION` in this state.
+            CREATING = 1
+
+            # The backup is complete and ready for use.
+            READY = 2
+          end
+        end
+
+        # Information about a backup.
+        # @!attribute [rw] backup
+        #   @return [String]
+        #     Output only. Name of the backup.
+        # @!attribute [rw] start_time
+        #   @return [Google::Protobuf::Timestamp]
+        #     Output only. The time that the backup was started. Row data in the backup
+        #     will be no older than this timestamp.
+        # @!attribute [rw] end_time
+        #   @return [Google::Protobuf::Timestamp]
+        #     Output only. This time that the backup was finished. Row data in the
+        #     backup will be no newer than this timestamp.
+        # @!attribute [rw] source_table
+        #   @return [String]
+        #     Output only. Name of the table the backup was created from.
+        class BackupInfo; end
+
+        # Indicates the type of the restore source.
+        module RestoreSourceType
+          # No restore associated.
+          RESTORE_SOURCE_TYPE_UNSPECIFIED = 0
+
+          # A backup was used as the source of the restore.
+          BACKUP = 1
+        end
       end
     end
   end

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

@@ -97,7 +97,7 @@ module Google
           # @yield [app_profile] The block for accessing each app profile.
           # @yieldparam [AppProfile] app_profile The app profile object.
           #
-          # @return [Enumerator]
+          # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
           #
           # @example Iterating each app profile by passing a block:
           #   require "google/cloud/bigtable"
@@ -118,7 +118,7 @@ module Google
           #
           #   instance = bigtable.instance("my-instance")
           #
-          #   all_snapshot_ids = instance.app_profiles.all.map do |app_profile|
+          #   all_app_profile_ids = instance.app_profiles.all.map do |app_profile|
           #     app_profile.name
           #   end
           #

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

@@ -0,0 +1,324 @@
+# 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.
+
+
+require "google/cloud/bigtable/backup/job"
+require "google/cloud/bigtable/backup/list"
+require "google/cloud/bigtable/convert"
+require "google/cloud/bigtable/table/restore_job"
+
+
+module Google
+  module Cloud
+    module Bigtable
+      ##
+      # # Backup
+      #
+      # A backup of a Cloud Bigtable table. See {Cluster#create_backup}, {Cluster#backup} and {Cluster#backups}.
+      #
+      # @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")
+      #
+      #   # Update
+      #   backup.expire_time = Time.now + 60 * 60 * 7
+      #   backup.save
+      #
+      #   # Delete
+      #   backup.delete
+      #
+      class Backup
+        # @private
+        # The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # @private A list of attributes that were updated.
+        attr_reader :updates
+
+        # @private
+        #
+        # Creates a new Backup instance.
+        def initialize grpc, service
+          @grpc = grpc
+          @service = service
+        end
+
+        ##
+        # The unique identifier for the project to which the backup belongs.
+        #
+        # @return [String]
+        #
+        def project_id
+          @grpc.name.split("/")[1]
+        end
+
+        ##
+        # The unique identifier for the instance to which the backup belongs.
+        #
+        # @return [String]
+        #
+        def instance_id
+          @grpc.name.split("/")[3]
+        end
+
+        ##
+        # The unique identifier for the cluster to which the backup belongs.
+        #
+        # @return [String]
+        #
+        def cluster_id
+          @grpc.name.split("/")[5]
+        end
+
+        ##
+        # The unique identifier for the backup.
+        #
+        # @return [String]
+        #
+        def backup_id
+          @grpc.name.split("/")[7]
+        end
+
+        ##
+        # The unique name of the backup. Value in the form
+        # `projects/<project>/instances/<instance>/clusters/<cluster>/backups/<backup>`.
+        #
+        # @return [String]
+        #
+        def path
+          @grpc.name
+        end
+
+        ##
+        # The table from which this backup was created.
+        #
+        # @param perform_lookup [Boolean] Creates table object without verifying that the table resource exists. Calls
+        #   made on this object will raise errors if the table does not exist. Default value is `false`. Optional. Helps
+        #   to reduce admin API calls.
+        # @param view [Symbol] Table view type. Default view type is `:SCHEMA_VIEW`. Valid view types are:
+        #
+        #   * `:NAME_ONLY` - Only populates `name`.
+        #   * `:SCHEMA_VIEW` - Only populates `name` and fields related to the table's schema.
+        #   * `:REPLICATION_VIEW` - Only populates `name` and fields related to the table's replication state.
+        #   * `:FULL` - Populates all fields.
+        #
+        # @return [Table]
+        #
+        def source_table perform_lookup: nil, view: nil
+          table = Table.from_path @grpc.source_table, service
+          return table.reload! view: view if perform_lookup
+          table
+        end
+
+        ##
+        # 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.
+        #
+        # @return [Time]
+        #
+        def expire_time
+          Convert.timestamp_to_time @grpc.expire_time
+        end
+
+        ##
+        # Sets 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.
+        #
+        # @param [Time] new_expire_time The new expiration time of the backup.
+        #
+        def expire_time= new_expire_time
+          @grpc.expire_time = Convert.time_to_timestamp new_expire_time
+        end
+
+        ##
+        # The time that the backup was started (i.e. approximately the time the `CreateBackup` request is received). The
+        # row data in this backup will be no older than this timestamp.
+        #
+        # @return [Time]
+        #
+        def start_time
+          Convert.timestamp_to_time @grpc.start_time
+        end
+
+        ##
+        # The time that the backup was finished. The row data in the backup will be no newer than this timestamp.
+        #
+        # @return [Time]
+        #
+        def end_time
+          Convert.timestamp_to_time @grpc.end_time
+        end
+
+        ##
+        # The size of the backup in bytes.
+        #
+        # @return [Integer]
+        #
+        def size_bytes
+          @grpc.size_bytes
+        end
+
+        ##
+        # The current state of the backup. Possible values are `:CREATING` and `:READY`.
+        #
+        # @return [Symbol]
+        #
+        def state
+          @grpc.state
+        end
+
+        ##
+        # The backup is currently being created, and may be destroyed if the creation process encounters an error.
+        #
+        # @return [Boolean]
+        #
+        def creating?
+          state == :CREATING
+        end
+
+        ##
+        # The backup has been successfully created and is ready to serve requests.
+        #
+        # @return [Boolean]
+        #
+        def ready?
+          state == :READY
+        end
+
+        ##
+        # Creates 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. Required.
+        #
+        # @return [Google::Cloud::Bigtable::Table::RestoreJob] The job representing the long-running, asynchronous
+        #   processing of a backup restore table operation.
+        #
+        # @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")
+        #
+        #   job = backup.restore("my-new-table")
+        #
+        #   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
+          grpc = service.restore_table table_id, instance_id, cluster_id, backup_id
+          Table::RestoreJob.from_grpc grpc, service
+        end
+
+        ##
+        # Updates the backup.
+        #
+        # `expire_time` is the only updatable field.
+        #
+        # @return [Boolean] Returns `true` if the update succeeded.
+        #
+        # @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")
+        #
+        #   # Update
+        #   backup.expire_time = Time.now + 60 * 60 * 7
+        #   backup.save
+        #
+        def save
+          ensure_service!
+          @grpc = service.update_backup @grpc, [:expire_time]
+          true
+        end
+        alias update save
+
+        ##
+        # Reloads backup data.
+        #
+        # @return [Google::Cloud::Bigtable::Backup]
+        #
+        def reload!
+          @grpc = service.get_backup instance_id, cluster_id, backup_id
+          self
+        end
+
+        ##
+        # Permanently deletes the backup.
+        #
+        # @return [Boolean] Returns `true` if the backup was deleted.
+        #
+        # @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")
+        #
+        #   backup.delete
+        #
+        def delete
+          ensure_service!
+          service.delete_backup instance_id, cluster_id, backup_id
+          true
+        end
+
+        # @private
+        #
+        # Creates a new Backup instance from a Google::Bigtable::Admin::V2::Backup.
+        #
+        # @param grpc [Google::Bigtable::Admin::V2::Backup]
+        # @param service [Google::Cloud::Bigtable::Service]
+        # @return [Google::Cloud::Bigtable::Backup]
+        def self.from_grpc grpc, service
+          new grpc, service
+        end
+
+        protected
+
+        # @private
+        #
+        # Raise an error unless an active connection to the service is available.
+        def ensure_service!
+          raise "Must have active connection to service" unless service
+        end
+      end
+    end
+  end
+end