google-cloud-spanner 2.22.0 → 2.23.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.
@@ -18,6 +18,7 @@ require "google/cloud/spanner/results"
18
18
  require "google/cloud/spanner/commit"
19
19
  require "google/cloud/spanner/commit_response"
20
20
  require "google/cloud/spanner/batch_update"
21
+ require "google/cloud/spanner/batch_write"
21
22
 
22
23
  module Google
23
24
  module Cloud
@@ -564,6 +565,9 @@ module Google
564
565
  # @param [String] transaction_id The identifier of previously-started
565
566
  # transaction to be used instead of starting a new transaction.
566
567
  # Optional.
568
+ # @param [Boolean] exclude_txn_from_change_streams If set to true,
569
+ # mutations will not be recorded in change streams with DDL option
570
+ # `allow_txn_exclusion=true`. Used if starting a new transaction.
567
571
  # @param [Hash] commit_options A hash of commit options.
568
572
  # e.g., return_commit_stats. Commit options are optional.
569
573
  # The following options can be provided:
@@ -641,13 +645,14 @@ module Google
641
645
  # puts commit_resp.timestamp
642
646
  # puts commit_resp.stats.mutation_count
643
647
  #
644
- def commit transaction_id: nil, commit_options: nil,
645
- request_options: nil, call_options: nil
648
+ def commit transaction_id: nil, exclude_txn_from_change_streams: false,
649
+ commit_options: nil, request_options: nil, call_options: nil
646
650
  ensure_service!
647
651
  commit = Commit.new
648
652
  yield commit
649
653
  commit_resp = service.commit path, commit.mutations,
650
654
  transaction_id: transaction_id,
655
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams,
651
656
  commit_options: commit_options,
652
657
  request_options: request_options,
653
658
  call_options: call_options
@@ -656,6 +661,103 @@ module Google
656
661
  commit_options ? resp : resp.timestamp
657
662
  end
658
663
 
664
+ ##
665
+ # Batches the supplied mutation groups in a collection of efficient
666
+ # transactions.
667
+ #
668
+ # All mutations in a group are committed atomically. However, mutations
669
+ # across groups can be committed non-atomically in an unspecified order
670
+ # and thus they must be independent of each other. Partial failure is
671
+ # possible, i.e., some groups may have been committed successfully,
672
+ # while others may have failed. The results of individual batches are
673
+ # streamed into the response as the batches are applied.
674
+ #
675
+ # BatchWrite requests are not replay protected, meaning that each mutation
676
+ # group may be applied more than once. Replays of non-idempotent mutations
677
+ # may have undesirable effects. For example, replays of an insert mutation
678
+ # may produce an already exists error or if you use generated or commit
679
+ # timestamp-based keys, it may result in additional rows being added to the
680
+ # mutation's table. We recommend structuring your mutation groups to be
681
+ # idempotent to avoid this issue.
682
+ #
683
+ # @param [Boolean] exclude_txn_from_change_streams If set to true,
684
+ # mutations will not be recorded in change streams with DDL option
685
+ # `allow_txn_exclusion=true`.
686
+ # @param [Hash] request_options Common request options.
687
+ #
688
+ # * `:priority` (String) The relative priority for requests.
689
+ # The priority acts as a hint to the Cloud Spanner scheduler
690
+ # and does not guarantee priority or order of execution.
691
+ # Valid values are `:PRIORITY_LOW`, `:PRIORITY_MEDIUM`,
692
+ # `:PRIORITY_HIGH`. If priority not set then default is
693
+ # `PRIORITY_UNSPECIFIED` is equivalent to `:PRIORITY_HIGH`.
694
+ # * `:tag` (String) A per-request tag which can be applied to
695
+ # queries or reads, used for statistics collection. Tag must be a
696
+ # valid identifier of the form: `[a-zA-Z][a-zA-Z0-9_\-]` between 2
697
+ # and 64 characters in length.
698
+ #
699
+ # @param [Hash] call_options A hash of values to specify the custom
700
+ # call options, e.g., timeout, retries, etc. Call options are
701
+ # optional. The following settings can be provided:
702
+ #
703
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
704
+ # that overrides the default setting.
705
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
706
+ # setting of retry policy with the following keys:
707
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
708
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
709
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
710
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
711
+ # trigger a retry.
712
+ #
713
+ # @yield [batch_write] a batch write object
714
+ # @yieldparam [Google::Cloud::Spanner::BatchWrite] batch_write a batch
715
+ # write object used to add mutaion groups through {MutationGroup}.
716
+ #
717
+ # @return [Google::Cloud::Spanner::BatchWriteResults] The results of
718
+ # the batch write operation. This is a stream of responses, each
719
+ # covering a set of the mutation groups that were either applied or
720
+ # failed together.
721
+ #
722
+ # @example
723
+ # require "google/cloud/spanner"
724
+ #
725
+ # spanner = Google::Cloud::Spanner.new
726
+ #
727
+ # db = spanner.client "my-instance", "my-database"
728
+ #
729
+ # results = db.batch_write do |b|
730
+ # # First mutation group
731
+ # b.mutation_group do |mg|
732
+ # mg.upsert "Singers", [{ SingerId: 16, FirstName: "Charlie", LastName: "Terry" }]
733
+ # end
734
+ #
735
+ # # Second mutation group
736
+ # b.mutation_group do |mg|
737
+ # mg.upsert "Singers", [{ SingerId: 17, FirstName: "Catalina", LastName: "Smith" }]
738
+ # mg.update "Albums", [{ SingerId: 17, AlbumId: 1, AlbumTitle: "Go Go Go" }]
739
+ # end
740
+ # end
741
+ #
742
+ # results.each do |response|
743
+ # puts "groups applied: #{response.indexes}" if response.ok?
744
+ # end
745
+ #
746
+ def batch_write exclude_txn_from_change_streams: false,
747
+ request_options: nil,
748
+ call_options: nil
749
+ ensure_service!
750
+ b = BatchWrite.new
751
+ yield b
752
+ response = service.batch_write path, b.mutation_groups_grpc,
753
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams,
754
+ request_options: request_options,
755
+ call_options: call_options
756
+ results = BatchWriteResults.new response
757
+ @last_updated_at = Time.now
758
+ results
759
+ end
760
+
659
761
  ##
660
762
  # Inserts or updates rows in a table. If any of the rows already exist,
661
763
  # then its column values are overwritten with the ones provided. Any
@@ -685,6 +787,12 @@ module Google
685
787
  # See [Data
686
788
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
687
789
  #
790
+ # @param [String] transaction_id The identifier of previously-started
791
+ # transaction to be used instead of starting a new transaction.
792
+ # Optional.
793
+ # @param [Boolean] exclude_txn_from_change_streams If set to true,
794
+ # mutations will not be recorded in change streams with DDL option
795
+ # `allow_txn_exclusion=true`. Used if starting a new transaction.
688
796
  # @param [Hash] commit_options A hash of commit options.
689
797
  # e.g., return_commit_stats. Commit options are optional.
690
798
  # The following options can be provided:
@@ -755,10 +863,12 @@ module Google
755
863
  # puts commit_resp.timestamp
756
864
  # puts commit_resp.stats.mutation_count
757
865
  #
758
- def upsert table, *rows, transaction_id: nil, commit_options: nil,
759
- request_options: nil, call_options: nil
866
+ def upsert table, *rows,
867
+ transaction_id: nil, exclude_txn_from_change_streams: false,
868
+ commit_options: nil, request_options: nil, call_options: nil
760
869
  opts = {
761
870
  transaction_id: transaction_id,
871
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams,
762
872
  commit_options: commit_options,
763
873
  request_options: request_options,
764
874
  call_options: call_options
@@ -797,6 +907,12 @@ module Google
797
907
  # See [Data
798
908
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
799
909
  #
910
+ # @param [String] transaction_id The identifier of previously-started
911
+ # transaction to be used instead of starting a new transaction.
912
+ # Optional.
913
+ # @param [Boolean] exclude_txn_from_change_streams If set to true,
914
+ # mutations will not be recorded in change streams with DDL option
915
+ # `allow_txn_exclusion=true`. Used if starting a new transaction.
800
916
  # @param [Hash] commit_options A hash of commit options.
801
917
  # e.g., return_commit_stats. Commit options are optional.
802
918
  # The following options can be provided:
@@ -867,10 +983,12 @@ module Google
867
983
  # puts commit_resp.timestamp
868
984
  # puts commit_resp.stats.mutation_count
869
985
  #
870
- def insert table, *rows, transaction_id: nil, commit_options: nil,
871
- request_options: nil, call_options: nil
986
+ def insert table, *rows,
987
+ transaction_id: nil, exclude_txn_from_change_streams: false,
988
+ commit_options: nil, request_options: nil, call_options: nil
872
989
  opts = {
873
990
  transaction_id: transaction_id,
991
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams,
874
992
  commit_options: commit_options,
875
993
  request_options: request_options,
876
994
  call_options: call_options
@@ -908,6 +1026,12 @@ module Google
908
1026
  # See [Data
909
1027
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
910
1028
  #
1029
+ # @param [String] transaction_id The identifier of previously-started
1030
+ # transaction to be used instead of starting a new transaction.
1031
+ # Optional.
1032
+ # @param [Boolean] exclude_txn_from_change_streams If set to true,
1033
+ # mutations will not be recorded in change streams with DDL option
1034
+ # `allow_txn_exclusion=true`. Used if starting a new transaction.
911
1035
  # @param [Hash] commit_options A hash of commit options.
912
1036
  # e.g., return_commit_stats. Commit options are optional.
913
1037
  # The following options can be provided:
@@ -978,10 +1102,12 @@ module Google
978
1102
  # puts commit_resp.timestamp
979
1103
  # puts commit_resp.stats.mutation_count
980
1104
  #
981
- def update table, *rows, transaction_id: nil, commit_options: nil,
982
- request_options: nil, call_options: nil
1105
+ def update table, *rows,
1106
+ transaction_id: nil, exclude_txn_from_change_streams: false,
1107
+ commit_options: nil, request_options: nil, call_options: nil
983
1108
  opts = {
984
1109
  transaction_id: transaction_id,
1110
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams,
985
1111
  commit_options: commit_options,
986
1112
  request_options: request_options,
987
1113
  call_options: call_options
@@ -1021,6 +1147,12 @@ module Google
1021
1147
  # See [Data
1022
1148
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
1023
1149
  #
1150
+ # @param [String] transaction_id The identifier of previously-started
1151
+ # transaction to be used instead of starting a new transaction.
1152
+ # Optional.
1153
+ # @param [Boolean] exclude_txn_from_change_streams If set to true,
1154
+ # mutations will not be recorded in change streams with DDL option
1155
+ # `allow_txn_exclusion=true`. Used if starting a new transaction.
1024
1156
  # @param [Hash] commit_options A hash of commit options.
1025
1157
  # e.g., return_commit_stats. Commit options are optional.
1026
1158
  # The following options can be provided:
@@ -1092,10 +1224,12 @@ module Google
1092
1224
  # puts commit_resp.timestamp
1093
1225
  # puts commit_resp.stats.mutation_count
1094
1226
  #
1095
- def replace table, *rows, transaction_id: nil, commit_options: nil,
1096
- request_options: nil, call_options: nil
1227
+ def replace table, *rows,
1228
+ transaction_id: nil, exclude_txn_from_change_streams: false,
1229
+ commit_options: nil, request_options: nil, call_options: nil
1097
1230
  opts = {
1098
1231
  transaction_id: transaction_id,
1232
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams,
1099
1233
  commit_options: commit_options,
1100
1234
  request_options: request_options,
1101
1235
  call_options: call_options
@@ -1114,6 +1248,12 @@ module Google
1114
1248
  # @param [Object, Array<Object>] keys A single, or list of keys or key
1115
1249
  # ranges to match returned data to. Values should have exactly as many
1116
1250
  # elements as there are columns in the primary key.
1251
+ # @param [String] transaction_id The identifier of previously-started
1252
+ # transaction to be used instead of starting a new transaction.
1253
+ # Optional.
1254
+ # @param [Boolean] exclude_txn_from_change_streams If set to true,
1255
+ # mutations will not be recorded in change streams with DDL option
1256
+ # `allow_txn_exclusion=true`. Used if starting a new transaction.
1117
1257
  # @param [Hash] commit_options A hash of commit options.
1118
1258
  # e.g., return_commit_stats. Commit options are optional.
1119
1259
  # The following options can be provided:
@@ -1181,10 +1321,12 @@ module Google
1181
1321
  # puts commit_resp.timestamp
1182
1322
  # puts commit_resp.stats.mutation_count
1183
1323
  #
1184
- def delete table, keys = [], transaction_id: nil, commit_options: nil,
1185
- request_options: nil, call_options: nil
1324
+ def delete table, keys = [],
1325
+ transaction_id: nil, exclude_txn_from_change_streams: false,
1326
+ commit_options: nil, request_options: nil, call_options: nil
1186
1327
  opts = {
1187
1328
  transaction_id: transaction_id,
1329
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams,
1188
1330
  commit_options: commit_options,
1189
1331
  request_options: request_options,
1190
1332
  call_options: call_options
@@ -1205,18 +1347,20 @@ module Google
1205
1347
  ##
1206
1348
  # @private
1207
1349
  # Creates a new transaction object every time.
1208
- def create_transaction
1350
+ def create_transaction exclude_txn_from_change_streams: false
1209
1351
  route_to_leader = LARHeaders.begin_transaction true
1210
- tx_grpc = service.begin_transaction path, route_to_leader: route_to_leader
1211
- Transaction.from_grpc tx_grpc, self
1352
+ tx_grpc = service.begin_transaction path,
1353
+ route_to_leader: route_to_leader,
1354
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams
1355
+ Transaction.from_grpc tx_grpc, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams
1212
1356
  end
1213
1357
 
1214
1358
  ##
1215
1359
  # @private
1216
1360
  # Creates a new transaction object without the grpc object
1217
1361
  # within it. Use it for inline-begin of a transaction.
1218
- def create_empty_transaction
1219
- Transaction.from_grpc nil, self
1362
+ def create_empty_transaction exclude_txn_from_change_streams: false
1363
+ Transaction.from_grpc nil, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams
1220
1364
  end
1221
1365
 
1222
1366
  ##
@@ -85,9 +85,13 @@ module Google
85
85
  # @private Transaction tag for statistics collection.
86
86
  attr_accessor :transaction_tag
87
87
 
88
+ # @private Whether to exclude from change streams.
89
+ attr_accessor :exclude_txn_from_change_streams
90
+
88
91
  def initialize
89
92
  @commit = Commit.new
90
93
  @seqno = 0
94
+ @exclude_txn_from_change_streams = false
91
95
 
92
96
  # Mutex to enfore thread safety for transaction creation and query executions.
93
97
  #
@@ -1152,10 +1156,11 @@ module Google
1152
1156
  ##
1153
1157
  # @private Creates a new Transaction instance from a
1154
1158
  # `Google::Cloud::Spanner::V1::Transaction`.
1155
- def self.from_grpc grpc, session
1159
+ def self.from_grpc grpc, session, exclude_txn_from_change_streams: false
1156
1160
  new.tap do |s|
1157
1161
  s.instance_variable_set :@grpc, grpc
1158
1162
  s.instance_variable_set :@session, session
1163
+ s.exclude_txn_from_change_streams = exclude_txn_from_change_streams
1159
1164
  end
1160
1165
  end
1161
1166
 
@@ -1216,11 +1221,12 @@ module Google
1216
1221
  #
1217
1222
  # This method is expected to be called from within `safe_execute()` method's block,
1218
1223
  # since it provides synchronization and gurantees thread safety.
1219
- def tx_selector
1224
+ def tx_selector exclude_txn_from_change_streams: false
1220
1225
  return V1::TransactionSelector.new id: transaction_id if existing_transaction?
1221
1226
  V1::TransactionSelector.new(
1222
1227
  begin: V1::TransactionOptions.new(
1223
- read_write: V1::TransactionOptions::ReadWrite.new
1228
+ read_write: V1::TransactionOptions::ReadWrite.new,
1229
+ exclude_txn_from_change_streams: exclude_txn_from_change_streams
1224
1230
  )
1225
1231
  )
1226
1232
  end
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module Spanner
19
- VERSION = "2.22.0".freeze
19
+ VERSION = "2.23.0".freeze
20
20
  end
21
21
  end
22
22
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: google-cloud-spanner
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.22.0
4
+ version: 2.23.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Mike Moore
@@ -9,38 +9,52 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2024-04-01 00:00:00.000000000 Z
12
+ date: 2024-06-27 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
- name: google-cloud-core
15
+ name: bigdecimal
16
16
  requirement: !ruby/object:Gem::Requirement
17
17
  requirements:
18
18
  - - "~>"
19
19
  - !ruby/object:Gem::Version
20
- version: '1.5'
20
+ version: '3.0'
21
21
  type: :runtime
22
22
  prerelease: false
23
23
  version_requirements: !ruby/object:Gem::Requirement
24
24
  requirements:
25
25
  - - "~>"
26
26
  - !ruby/object:Gem::Version
27
- version: '1.5'
27
+ version: '3.0'
28
28
  - !ruby/object:Gem::Dependency
29
- name: google-cloud-spanner-admin-database-v1
29
+ name: concurrent-ruby
30
30
  requirement: !ruby/object:Gem::Requirement
31
31
  requirements:
32
32
  - - "~>"
33
33
  - !ruby/object:Gem::Version
34
- version: '0.1'
34
+ version: '1.0'
35
35
  type: :runtime
36
36
  prerelease: false
37
37
  version_requirements: !ruby/object:Gem::Requirement
38
38
  requirements:
39
39
  - - "~>"
40
40
  - !ruby/object:Gem::Version
41
- version: '0.1'
41
+ version: '1.0'
42
42
  - !ruby/object:Gem::Dependency
43
- name: google-cloud-spanner-admin-instance-v1
43
+ name: google-cloud-core
44
+ requirement: !ruby/object:Gem::Requirement
45
+ requirements:
46
+ - - "~>"
47
+ - !ruby/object:Gem::Version
48
+ version: '1.5'
49
+ type: :runtime
50
+ prerelease: false
51
+ version_requirements: !ruby/object:Gem::Requirement
52
+ requirements:
53
+ - - "~>"
54
+ - !ruby/object:Gem::Version
55
+ version: '1.5'
56
+ - !ruby/object:Gem::Dependency
57
+ name: google-cloud-spanner-admin-database-v1
44
58
  requirement: !ruby/object:Gem::Requirement
45
59
  requirements:
46
60
  - - "~>"
@@ -54,33 +68,33 @@ dependencies:
54
68
  - !ruby/object:Gem::Version
55
69
  version: '0.1'
56
70
  - !ruby/object:Gem::Dependency
57
- name: google-cloud-spanner-v1
71
+ name: google-cloud-spanner-admin-instance-v1
58
72
  requirement: !ruby/object:Gem::Requirement
59
73
  requirements:
60
74
  - - "~>"
61
75
  - !ruby/object:Gem::Version
62
- version: '0.2'
76
+ version: '0.1'
63
77
  type: :runtime
64
78
  prerelease: false
65
79
  version_requirements: !ruby/object:Gem::Requirement
66
80
  requirements:
67
81
  - - "~>"
68
82
  - !ruby/object:Gem::Version
69
- version: '0.2'
83
+ version: '0.1'
70
84
  - !ruby/object:Gem::Dependency
71
- name: concurrent-ruby
85
+ name: google-cloud-spanner-v1
72
86
  requirement: !ruby/object:Gem::Requirement
73
87
  requirements:
74
88
  - - "~>"
75
89
  - !ruby/object:Gem::Version
76
- version: '1.0'
90
+ version: '0.2'
77
91
  type: :runtime
78
92
  prerelease: false
79
93
  version_requirements: !ruby/object:Gem::Requirement
80
94
  requirements:
81
95
  - - "~>"
82
96
  - !ruby/object:Gem::Version
83
- version: '1.0'
97
+ version: '0.2'
84
98
  description: google-cloud-spanner is the official library for Google Cloud Spanner
85
99
  API.
86
100
  email:
@@ -114,6 +128,8 @@ files:
114
128
  - lib/google/cloud/spanner/batch_snapshot.rb
115
129
  - lib/google/cloud/spanner/batch_update.rb
116
130
  - lib/google/cloud/spanner/batch_update_results.rb
131
+ - lib/google/cloud/spanner/batch_write.rb
132
+ - lib/google/cloud/spanner/batch_write_results.rb
117
133
  - lib/google/cloud/spanner/client.rb
118
134
  - lib/google/cloud/spanner/column_value.rb
119
135
  - lib/google/cloud/spanner/commit.rb
@@ -136,6 +152,7 @@ files:
136
152
  - lib/google/cloud/spanner/instance/job.rb
137
153
  - lib/google/cloud/spanner/instance/list.rb
138
154
  - lib/google/cloud/spanner/lar_headers.rb
155
+ - lib/google/cloud/spanner/mutation_group.rb
139
156
  - lib/google/cloud/spanner/partition.rb
140
157
  - lib/google/cloud/spanner/policy.rb
141
158
  - lib/google/cloud/spanner/pool.rb