google-cloud-bigtable 1.0.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +34 -0
  3. data/TROUBLESHOOTING.md +2 -8
  4. data/lib/google/bigtable/admin/v2/bigtable_instance_admin_pb.rb +27 -24
  5. data/lib/google/bigtable/admin/v2/bigtable_instance_admin_services_pb.rb +60 -57
  6. data/lib/google/bigtable/admin/v2/bigtable_table_admin_pb.rb +90 -23
  7. data/lib/google/bigtable/admin/v2/bigtable_table_admin_services_pb.rb +125 -98
  8. data/lib/google/bigtable/admin/v2/common_pb.rb +9 -4
  9. data/lib/google/bigtable/admin/v2/instance_pb.rb +12 -11
  10. data/lib/google/bigtable/admin/v2/table_pb.rb +52 -14
  11. data/lib/google/bigtable/v2/bigtable_pb.rb +17 -17
  12. data/lib/google/bigtable/v2/bigtable_services_pb.rb +39 -39
  13. data/lib/google/bigtable/v2/data_pb.rb +21 -21
  14. data/lib/google/cloud/bigtable/admin.rb +3 -3
  15. data/lib/google/cloud/bigtable/admin/v2.rb +4 -3
  16. data/lib/google/cloud/bigtable/admin/v2/bigtable_instance_admin_client.rb +60 -50
  17. data/lib/google/cloud/bigtable/admin/v2/bigtable_instance_admin_client_config.json +1 -1
  18. data/lib/google/cloud/bigtable/admin/v2/bigtable_table_admin_client.rb +547 -58
  19. data/lib/google/cloud/bigtable/admin/v2/bigtable_table_admin_client_config.json +31 -1
  20. data/lib/google/cloud/bigtable/admin/v2/doc/google/bigtable/admin/v2/bigtable_instance_admin.rb +46 -39
  21. data/lib/google/cloud/bigtable/admin/v2/doc/google/bigtable/admin/v2/bigtable_table_admin.rb +281 -53
  22. data/lib/google/cloud/bigtable/admin/v2/doc/google/bigtable/admin/v2/instance.rb +15 -17
  23. data/lib/google/cloud/bigtable/admin/v2/doc/google/bigtable/admin/v2/table.rb +119 -26
  24. data/lib/google/cloud/bigtable/app_profile/list.rb +2 -2
  25. data/lib/google/cloud/bigtable/backup.rb +324 -0
  26. data/lib/google/cloud/bigtable/backup/job.rb +87 -0
  27. data/lib/google/cloud/bigtable/backup/list.rb +167 -0
  28. data/lib/google/cloud/bigtable/cluster.rb +99 -0
  29. data/lib/google/cloud/bigtable/cluster/list.rb +1 -1
  30. data/lib/google/cloud/bigtable/column_family_map.rb +1 -1
  31. data/lib/google/cloud/bigtable/instance.rb +4 -7
  32. data/lib/google/cloud/bigtable/instance/list.rb +1 -1
  33. data/lib/google/cloud/bigtable/longrunning_job.rb +11 -0
  34. data/lib/google/cloud/bigtable/policy.rb +1 -1
  35. data/lib/google/cloud/bigtable/service.rb +131 -0
  36. data/lib/google/cloud/bigtable/table.rb +112 -0
  37. data/lib/google/cloud/bigtable/table/cluster_state.rb +25 -4
  38. data/lib/google/cloud/bigtable/table/list.rb +1 -1
  39. data/lib/google/cloud/bigtable/table/restore_job.rb +117 -0
  40. data/lib/google/cloud/bigtable/v2.rb +1 -1
  41. data/lib/google/cloud/bigtable/v2/bigtable_client.rb +3 -0
  42. data/lib/google/cloud/bigtable/v2/bigtable_client_config.json +7 -7
  43. data/lib/google/cloud/bigtable/version.rb +1 -1
  44. metadata +9 -5
@@ -640,6 +640,58 @@ module Google
640
640
  end
641
641
  end
642
642
 
643
+ ##
644
+ # Gets the access control policy for an table resource. Returns an empty
645
+ # policy if an table exists but does not have a policy set.
646
+ #
647
+ # @param table_id [String]
648
+ # Unique ID of the table for which the policy is being requested.
649
+ # @return [Google::Iam::V1::Policy]
650
+ #
651
+ def get_table_policy instance_id, table_id
652
+ execute do
653
+ tables.get_iam_policy table_path(instance_id, table_id)
654
+ end
655
+ end
656
+
657
+ ##
658
+ # Sets the access control policy on an table resource. Replaces any
659
+ # existing policy.
660
+ #
661
+ # @param table_id [String]
662
+ # Unique ID of the table the policy is for.
663
+ # @param policy [Google::Iam::V1::Policy | Hash]
664
+ # REQUIRED: The complete policy to be applied to the +resource+. The size of
665
+ # the policy is limited to a few 10s of KB. An empty policy is valid
666
+ # for Cloud Bigtable, but certain Cloud Platform services (such as Projects)
667
+ # might reject an empty policy.
668
+ # Alternatively, provide a hash similar to `Google::Iam::V1::Policy`.
669
+ # @return [Google::Iam::V1::Policy]
670
+ #
671
+ def set_table_policy instance_id, table_id, policy
672
+ execute do
673
+ tables.set_iam_policy table_path(instance_id, table_id), policy
674
+ end
675
+ end
676
+
677
+ ##
678
+ # Returns permissions that the caller has for the specified table resource.
679
+ #
680
+ # @param table_id [String]
681
+ # The table ID that the policy detail is being requested for.
682
+ # @param permissions [Array<String>]
683
+ # The set of permissions to check for the +resource+. Permissions with
684
+ # wildcards (such as '*' or 'storage.*') are not allowed. For more
685
+ # information see
686
+ # [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
687
+ # @return [Google::Iam::V1::TestIamPermissionsResponse]
688
+ #
689
+ def test_table_permissions instance_id, table_id, permissions
690
+ execute do
691
+ tables.test_iam_permissions table_path(instance_id, table_id), permissions
692
+ end
693
+ end
694
+
643
695
  def read_rows instance_id, table_id, app_profile_id: nil, rows: nil, filter: nil, rows_limit: nil
644
696
  # execute is not used because error handling is in ReadOperations#read_rows
645
697
  client.read_rows table_path(instance_id, table_id),
@@ -682,6 +734,75 @@ module Google
682
734
  end
683
735
  end
684
736
 
737
+ ##
738
+ # Starts creating a new backup. The underlying Google::Longrunning::Operation tracks creation of the backup.
739
+ #
740
+ # @return [Google::Gax::Operation]
741
+ #
742
+ def create_backup instance_id:, cluster_id:, backup_id:, source_table_id:, expire_time:
743
+ backup = Google::Bigtable::Admin::V2::Backup.new source_table: table_path(instance_id, source_table_id),
744
+ expire_time: expire_time
745
+ execute do
746
+ tables.create_backup cluster_path(instance_id, cluster_id), backup_id, backup
747
+ end
748
+ end
749
+
750
+ ##
751
+ # @return [Google::Bigtable::Admin::V2::Backup]
752
+ #
753
+ def get_backup instance_id, cluster_id, backup_id
754
+ execute do
755
+ tables.get_backup backup_path(instance_id, cluster_id, backup_id)
756
+ end
757
+ end
758
+
759
+ ##
760
+ # @return [Google::Gax::PagedEnumerable<Google::Bigtable::Admin::V2::Backup>]
761
+ #
762
+ def list_backups instance_id, cluster_id
763
+ execute do
764
+ tables.list_backups cluster_path(instance_id, cluster_id)
765
+ end
766
+ end
767
+
768
+ ##
769
+ # @param backup [Google::Bigtable::Admin::V2::Backup | Hash]
770
+ # @param fields [Array(String|Symbol)] the paths of fields to be updated
771
+ #
772
+ def update_backup backup, fields
773
+ mask = Google::Protobuf::FieldMask.new paths: fields.map(&:to_s)
774
+ execute do
775
+ tables.update_backup backup, mask
776
+ end
777
+ end
778
+
779
+ def delete_backup instance_id, cluster_id, backup_id
780
+ execute do
781
+ tables.delete_backup backup_path(instance_id, cluster_id, backup_id)
782
+ end
783
+ end
784
+
785
+ ##
786
+ # Create a new table by restoring from a completed backup.
787
+ #
788
+ # @param table_id [String] The table ID for the new table. This table must not yet exist.
789
+ # @param instance_id [String] The instance ID for the source backup. The table will be created in this instance.
790
+ # @param cluster_id [String] The cluster ID for the source backup.
791
+ # @param backup_id [String] The backup ID for the source backup.
792
+ #
793
+ # @return [Google::Gax::Operation] The {Google::Longrunning::Operation#metadata metadata} field type is
794
+ # {Google::Bigtable::Admin::RestoreTableMetadata RestoreTableMetadata}. The
795
+ # {Google::Longrunning::Operation#response response} type is {Google::Bigtable::Admin::V2::Table Table}, if
796
+ # successful.
797
+ #
798
+ def restore_table table_id, instance_id, cluster_id, backup_id
799
+ execute do
800
+ tables.restore_table instance_path(instance_id),
801
+ table_id: table_id,
802
+ backup: backup_path(instance_id, cluster_id, backup_id)
803
+ end
804
+ end
805
+
685
806
  ##
686
807
  # Executes the API call and wrap errors to {Google::Cloud::Error}.
687
808
  #
@@ -769,6 +890,16 @@ module Google
769
890
  Admin::V2::BigtableInstanceAdminClient.app_profile_path project_id, instance_id, app_profile_id
770
891
  end
771
892
 
893
+ ##
894
+ # Creates a formatted backup path.
895
+ #
896
+ # @return [String] Formatted backup path
897
+ # `projects/<project>/instances/<instance>/clusters/<cluster>/backups/<backup>`
898
+ #
899
+ def backup_path instance_id, cluster_id, backup_id
900
+ Admin::V2::BigtableTableAdminClient.backup_path project_id, instance_id, cluster_id, backup_id
901
+ end
902
+
772
903
  ##
773
904
  # Inspects the service object.
774
905
  # @return [String]
@@ -20,6 +20,7 @@ require "google/cloud/bigtable/table/cluster_state"
20
20
  require "google/cloud/bigtable/column_family_map"
21
21
  require "google/cloud/bigtable/gc_rule"
22
22
  require "google/cloud/bigtable/mutation_operations"
23
+ require "google/cloud/bigtable/policy"
23
24
  require "google/cloud/bigtable/read_operations"
24
25
 
25
26
  module Google
@@ -239,6 +240,117 @@ module Google
239
240
  granularity == :MILLIS
240
241
  end
241
242
 
243
+ ##
244
+ # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
245
+ # policy for the table.
246
+ #
247
+ # @see https://cloud.google.com/bigtable/docs/access-control
248
+ #
249
+ # @yield [policy] A block for updating the policy. The latest policy
250
+ # will be read from the Bigtable service and passed to the block. After
251
+ # the block completes, the modified policy will be written to the
252
+ # service.
253
+ # @yieldparam [Policy] policy the current Cloud IAM Policy for this
254
+ # table.
255
+ #
256
+ # @return [Policy] The current Cloud IAM Policy for the table.
257
+ #
258
+ # @example
259
+ # require "google/cloud/bigtable"
260
+ #
261
+ # bigtable = Google::Cloud::Bigtable.new
262
+ #
263
+ # table = bigtable.table("my-instance", "my-table", perform_lookup: true)
264
+ # policy = table.policy
265
+ #
266
+ # @example Update the policy by passing a block.
267
+ # require "google/cloud/bigtable"
268
+ #
269
+ # bigtable = Google::Cloud::Bigtable.new
270
+ #
271
+ # table = bigtable.table("my-instance", "my-table", perform_lookup: true)
272
+ #
273
+ # table.policy do |p|
274
+ # p.add("roles/owner", "user:owner@example.com")
275
+ # end # 2 API calls
276
+ #
277
+ def policy
278
+ ensure_service!
279
+ grpc = service.get_table_policy instance_id, name
280
+ policy = Policy.from_grpc grpc
281
+ return policy unless block_given?
282
+ yield policy
283
+ update_policy policy
284
+ end
285
+
286
+ ##
287
+ # Updates the [Cloud IAM](https://cloud.google.com/iam/) access control
288
+ # policy for the table. The policy should be read from {#policy}.
289
+ # See {Google::Cloud::Bigtable::Policy} for an explanation of the policy
290
+ # `etag` property and how to modify policies.
291
+ #
292
+ # You can also update the policy by passing a block to {#policy}, which
293
+ # will call this method internally after the block completes.
294
+ #
295
+ # @param new_policy [Policy] a new or modified Cloud IAM Policy for this
296
+ # table
297
+ #
298
+ # @return [Policy] The policy returned by the API update operation.
299
+ #
300
+ # @example
301
+ # require "google/cloud/bigtable"
302
+ #
303
+ # bigtable = Google::Cloud::Bigtable.new
304
+ #
305
+ # table = bigtable.table("my-instance", "my-table", perform_lookup: true)
306
+ #
307
+ # policy = table.policy
308
+ # policy.add("roles/owner", "user:owner@example.com")
309
+ # updated_policy = table.update_policy(policy)
310
+ #
311
+ # puts updated_policy.roles
312
+ #
313
+ def update_policy new_policy
314
+ ensure_service!
315
+ grpc = service.set_table_policy instance_id, name, new_policy.to_grpc
316
+ Policy.from_grpc grpc
317
+ end
318
+ alias policy= update_policy
319
+
320
+ ##
321
+ # Tests the specified permissions against the [Cloud
322
+ # IAM](https://cloud.google.com/iam/) access control policy.
323
+ #
324
+ # @see https://cloud.google.com/iam/docs/managing-policies Managing Policies
325
+ # @see https://cloud.google.com/bigtable/docs/access-control Access Control
326
+ #
327
+ # @param permissions [String, Array<String>] permissions The set of permissions to
328
+ # check access for. Permissions with wildcards (such as `*` or
329
+ # `bigtable.*`) are not allowed.
330
+ # See [Access Control](https://cloud.google.com/bigtable/docs/access-control).
331
+ #
332
+ # @return [Array<String>] The permissions that are configured for the policy.
333
+ #
334
+ # @example
335
+ # require "google/cloud/bigtable"
336
+ #
337
+ # bigtable = Google::Cloud::Bigtable.new
338
+ #
339
+ # table = bigtable.table("my-instance", "my-table", perform_lookup: true)
340
+ #
341
+ # permissions = table.test_iam_permissions(
342
+ # "bigtable.tables.delete",
343
+ # "bigtable.tables.get"
344
+ # )
345
+ # permissions.include? "bigtable.tables.delete" #=> false
346
+ # permissions.include? "bigtable.tables.get" #=> true
347
+ #
348
+ def test_iam_permissions *permissions
349
+ ensure_service!
350
+ grpc = service.test_table_permissions instance_id, name, permissions.flatten
351
+ grpc.permissions.to_a
352
+ end
353
+
242
354
  ##
243
355
  # Permanently deletes the table from a instance.
244
356
  #
@@ -21,6 +21,8 @@ module Google
21
21
  class Table
22
22
  ##
23
23
  # Table::ClusterState is the state of a table's data in a particular cluster.
24
+ #
25
+ # @attr [String] cluster_name The name of the cluster.
24
26
  class ClusterState
25
27
  attr_reader :cluster_name
26
28
 
@@ -39,6 +41,10 @@ module Google
39
41
  # * `:PLANNED_MAINTENANCE` - The table is temporarily unable to serve.
40
42
  # * `:UNPLANNED_MAINTENANCE` - The table is temporarily unable to serve.
41
43
  # * `:READY` - The table can serve.
44
+ # * `:READY_OPTIMIZING` - The table is fully created and ready for use
45
+ # after a restore, and is being optimized for performance. When
46
+ # optimizations are complete, the table will transition to `READY`
47
+ # state.
42
48
  #
43
49
  # @return [Symbol] The state of replication.
44
50
  #
@@ -51,7 +57,7 @@ module Google
51
57
  # over pre-existing data from other clusters before it can begin
52
58
  # receiving live replication updates and serving.
53
59
  #
54
- # @return [Boolean] `true` if the cluster is initializing.
60
+ # @return [Boolean] `true` if the table in this cluster is initializing.
55
61
  #
56
62
  def initializing?
57
63
  replication_state == :INITIALIZING
@@ -61,7 +67,8 @@ module Google
61
67
  # The table is temporarily unable to serve
62
68
  # requests from this cluster due to planned internal maintenance.
63
69
  #
64
- # @return [Boolean] `true` if the cluster is in planned maintenance.
70
+ # @return [Boolean] `true` if the table in this cluster is in planned
71
+ # maintenance.
65
72
  #
66
73
  def planned_maintenance?
67
74
  replication_state == :PLANNED_MAINTENANCE
@@ -71,7 +78,8 @@ module Google
71
78
  # The table is temporarily unable to serve requests from this
72
79
  # cluster due to unplanned or emergency maintenance.
73
80
  #
74
- # @return [Boolean] `true` if the cluster is in unplanned maintenance.
81
+ # @return [Boolean] `true` if the table in this cluster is in unplanned
82
+ # maintenance.
75
83
  #
76
84
  def unplanned_maintenance?
77
85
  replication_state == :UNPLANNED_MAINTENANCE
@@ -82,12 +90,25 @@ module Google
82
90
  # Depending on replication delay, reads may not immediately
83
91
  # reflect the state of the table in other clusters.
84
92
  #
85
- # @return [Boolean] `true` if the cluster is ready.
93
+ # @return [Boolean] `true` if the table in this cluster is ready.
86
94
  #
87
95
  def ready?
88
96
  replication_state == :READY
89
97
  end
90
98
 
99
+ ##
100
+ # The table is fully created and ready for use after a
101
+ # restore, and is being optimized for performance. When
102
+ # optimizations are complete, the table will transition to `READY`
103
+ # state.
104
+ #
105
+ # @return [Boolean] `true` if the table in this cluster is being
106
+ # optimized.
107
+ #
108
+ def ready_optimizing?
109
+ replication_state == :READY_OPTIMIZING
110
+ end
111
+
91
112
  # @private
92
113
  # New Table::ClusterState from a Google::Bigtable::Admin::V2::Table::ClusterState object.
93
114
  # @param grpc [Google::Bigtable::Admin::V2::Table::ClusterState]
@@ -94,7 +94,7 @@ module Google
94
94
  # @yield [table] The block for accessing each table instance.
95
95
  # @yieldparam [Table] table The table instance object.
96
96
  #
97
- # @return [Enumerator]
97
+ # @return [Enumerator,nil] An enumerator is returned if no block is given, otherwise `nil`.
98
98
  #
99
99
  # @example Iterating each table by passing a block:
100
100
  # require "google/cloud/bigtable"
@@ -0,0 +1,117 @@
1
+ # Copyright 2020 Google LLC
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # https://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ module Google
17
+ module Cloud
18
+ module Bigtable
19
+ class Table
20
+ ##
21
+ # # RestoreJob
22
+ #
23
+ # A resource representing the long-running, asynchronous processing of a backup restore operation. The
24
+ # job can be refreshed to retrieve the table object once the operation has been completed.
25
+ #
26
+ # See {Backup#restore}.
27
+ #
28
+ # @see https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.longrunning#google.longrunning.Operation
29
+ # Long-running Operation
30
+ #
31
+ # @example
32
+ # require "google/cloud/bigtable"
33
+ #
34
+ # bigtable = Google::Cloud::Bigtable.new
35
+ # instance = bigtable.instance("my-instance")
36
+ # cluster = instance.cluster("my-cluster")
37
+ #
38
+ # backup = cluster.backup("my-backup")
39
+ #
40
+ # job = backup.restore("my-new-table")
41
+ #
42
+ # job.wait_until_done!
43
+ # job.done? #=> true
44
+ #
45
+ # if job.error?
46
+ # status = job.error
47
+ # else
48
+ # table = job.table
49
+ # optimized = job.optimize_table_operation_name
50
+ # end
51
+ #
52
+ class RestoreJob < LongrunningJob
53
+ ##
54
+ # The optimize table operation name from operation metadata.
55
+ #
56
+ # @return [String, nil] The optimize table operation name, or `nil` if the optimize table operation is not
57
+ # complete.
58
+ #
59
+ # @example
60
+ # require "google/cloud/bigtable"
61
+ #
62
+ # bigtable = Google::Cloud::Bigtable.new
63
+ # instance = bigtable.instance("my-instance")
64
+ # cluster = instance.cluster("my-cluster")
65
+ #
66
+ # backup = cluster.backup("my-backup")
67
+ #
68
+ # job = backup.restore("my-new-table")
69
+ #
70
+ # job.wait_until_done!
71
+ # job.done? #=> true
72
+ #
73
+ # if job.error?
74
+ # status = job.error
75
+ # else
76
+ # table = job.table
77
+ # optimized = job.optimize_table_operation_name
78
+ # end
79
+ #
80
+ def optimize_table_operation_name
81
+ metadata.optimize_table_operation_name
82
+ end
83
+
84
+ ##
85
+ # Gets the table object from operation results.
86
+ #
87
+ # @return [Google::Cloud::Bigtable::Table, nil] The table instance, or `nil` if the operation is not complete.
88
+ #
89
+ # @example
90
+ # require "google/cloud/bigtable"
91
+ #
92
+ # bigtable = Google::Cloud::Bigtable.new
93
+ # instance = bigtable.instance("my-instance")
94
+ # cluster = instance.cluster("my-cluster")
95
+ #
96
+ # backup = cluster.backup("my-backup")
97
+ #
98
+ # job = backup.restore("my-new-table")
99
+ #
100
+ # job.wait_until_done!
101
+ # job.done? #=> true
102
+ #
103
+ # if job.error?
104
+ # status = job.error
105
+ # else
106
+ # table = job.table
107
+ # optimized = job.optimize_table_operation_name
108
+ # end
109
+ #
110
+ def table
111
+ Table.from_grpc results, service if results
112
+ end
113
+ end
114
+ end
115
+ end
116
+ end
117
+ end