google-cloud-spanner 2.2.0 → 2.3.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 01dd371ff37296529b691fd13961d7e7681e63480a88202b9e958a8c28bc480b
4
- data.tar.gz: 9915fdf52be7508c55380b193a9586a35c702617080d3bf93a9f53b37b62be84
3
+ metadata.gz: 62f5ce383d6aefe48214924e77b5a794bd0a0c03bb6acaedd383be12d47da9b9
4
+ data.tar.gz: ed1e49a6ef47946d557f8cb768d6da33923179fa05551ea7fadd55f3f5cfe341
5
5
  SHA512:
6
- metadata.gz: 0a34c4eeaaf84abe4d311350a155b22190c7dbc426a48719df4ad553692d841aa1a2d3a72d7f043b2fef7b3fa87a81cda69f965f5eef58a8ce17a77bf186a48e
7
- data.tar.gz: 36062397079b8960916575b9188c0ad10f376d27b7d194a20e7f4c6e69f29eeb018b499576209bf1b2d2985725233db5de3e233ff840b5c93790d15b9b4204ab
6
+ metadata.gz: 4b22e83c54208f8961e267a81ef681f98ef7e2ffe9a48274e566899adfed7c514c3a124b9f747667908db89067cbe0715f8c1363635d75cd4461f9072f703819
7
+ data.tar.gz: '085550ca4945d0436fd92f94adb16464d30224f5f466ca1f3becb24bdcf0b8bc4fa0416d2f26ecc375ca71eadface1856702dac02a7093bda001ce4e37be359d'
data/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Release History
2
2
 
3
+ ### 2.3.0 / 2021-02-09
4
+
5
+ #### Features
6
+
7
+ * CommitStats in CommitResponse ([#8058](https://www.github.com/googleapis/google-cloud-ruby/issues/8058))
8
+ * optionalize `credentials` when using cloud spanner emulator host ([#8416](https://www.github.com/googleapis/google-cloud-ruby/issues/8416))
9
+ * Optionalize `credentials` when using Cloud Spanner Emulator
10
+ * Remove unnecessary credentials stub for emulator_host in Google::Cloud::Spanner.new
11
+ * Add test of explicit project_id in Google::Cloud::Spanner.new
12
+ * Update document for `emulator_host` without credentials
13
+ * Tidy code according to rubocop settings
14
+
3
15
  ### 2.2.0 / 2020-09-15
4
16
 
5
17
  #### Features
data/CONTRIBUTING.md CHANGED
@@ -45,7 +45,7 @@ there is a small amount of setup:
45
45
 
46
46
  ```sh
47
47
  $ cd google-cloud-spanner/
48
- $ bundle exec rake bundleupdate
48
+ $ bundle install
49
49
  ```
50
50
 
51
51
  ## Console
@@ -49,6 +49,8 @@ module Google
49
49
  # @param [String, Hash, Google::Auth::Credentials] credentials The path to
50
50
  # the keyfile as a String, the contents of the keyfile as a Hash, or a
51
51
  # Google::Auth::Credentials object. (See {Spanner::Credentials})
52
+ # If `emulator_host` is present, this becomes optional and the value is
53
+ # internally overriden with `:this_channel_is_insecure`.
52
54
  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
53
55
  # the set of resources and operations that the connection can access.
54
56
  # See [Using OAuth 2.0 to Access Google
@@ -60,7 +62,7 @@ module Google
60
62
  # * `https://www.googleapis.com/auth/spanner.data`
61
63
  # @param [Integer] timeout Default timeout to use in requests. Optional.
62
64
  # @param [String] endpoint Override of the endpoint host name. Optional.
63
- # If the param is nil, uses the default endpoint.
65
+ # If the param is nil, uses `emulator_host` or the default endpoint.
64
66
  # @param [String] project Alias for the `project_id` argument. Deprecated.
65
67
  # @param [String] keyfile Alias for the `credentials` argument.
66
68
  # Deprecated.
@@ -91,19 +93,19 @@ module Google
91
93
  def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
92
94
  endpoint: nil, project: nil, keyfile: nil,
93
95
  emulator_host: nil, lib_name: nil, lib_version: nil
94
- project_id ||= (project || default_project_id)
96
+ project_id ||= project || default_project_id
95
97
  scope ||= configure.scope
96
98
  timeout ||= configure.timeout
97
- endpoint ||= configure.endpoint
98
- credentials ||= (keyfile || default_credentials(scope: scope))
99
99
  emulator_host ||= configure.emulator_host
100
+ endpoint ||= emulator_host || configure.endpoint
101
+ credentials ||= keyfile
100
102
  lib_name ||= configure.lib_name
101
103
  lib_version ||= configure.lib_version
102
104
 
103
105
  if emulator_host
104
106
  credentials = :this_channel_is_insecure
105
- endpoint = emulator_host
106
107
  else
108
+ credentials ||= default_credentials scope: scope
107
109
  unless credentials.is_a? Google::Auth::Credentials
108
110
  credentials = Spanner::Credentials.new credentials, scope: scope
109
111
  end
@@ -23,6 +23,7 @@ require "google/cloud/spanner/snapshot"
23
23
  require "google/cloud/spanner/range"
24
24
  require "google/cloud/spanner/column_value"
25
25
  require "google/cloud/spanner/convert"
26
+ require "google/cloud/spanner/commit_response"
26
27
 
27
28
  module Google
28
29
  module Cloud
@@ -809,7 +810,16 @@ module Google
809
810
  # See [Data
810
811
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
811
812
  #
812
- # @return [Time] The timestamp at which the operation committed.
813
+ # @param [Hash] commit_options A hash of commit options.
814
+ # e.g., return_commit_stats. Commit options are optional.
815
+ # The following options can be provided:
816
+ #
817
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
818
+ # then statistics related to the transaction will be included in
819
+ # {CommitResponse}. Default value is `false`
820
+ #
821
+ # @return [Time, CommitResponse] The timestamp at which the operation
822
+ # committed. If commit options are set it returns {CommitResponse}.
813
823
  #
814
824
  # @example
815
825
  # require "google/cloud/spanner"
@@ -821,9 +831,24 @@ module Google
821
831
  # db.upsert "users", [{ id: 1, name: "Charlie", active: false },
822
832
  # { id: 2, name: "Harvey", active: true }]
823
833
  #
824
- def upsert table, *rows
834
+ # @example Get commit stats
835
+ # require "google/cloud/spanner"
836
+ #
837
+ # spanner = Google::Cloud::Spanner.new
838
+ #
839
+ # db = spanner.client "my-instance", "my-database"
840
+ #
841
+ # records = [{ id: 1, name: "Charlie", active: false },
842
+ # { id: 2, name: "Harvey", active: true }]
843
+ # commit_options = { return_commit_stats: true }
844
+ # commit_resp = db.upsert "users", records, commit_options: commit_options
845
+ #
846
+ # puts commit_resp.timestamp
847
+ # puts commit_resp.stats.mutation_count
848
+ #
849
+ def upsert table, rows, commit_options: nil
825
850
  @pool.with_session do |session|
826
- session.upsert table, rows
851
+ session.upsert table, rows, commit_options: commit_options
827
852
  end
828
853
  end
829
854
  alias save upsert
@@ -865,7 +890,16 @@ module Google
865
890
  # See [Data
866
891
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
867
892
  #
868
- # @return [Time] The timestamp at which the operation committed.
893
+ # @param [Hash] commit_options A hash of commit options.
894
+ # e.g., return_commit_stats. Commit options are optional.
895
+ # The following options can be provided:
896
+ #
897
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
898
+ # then statistics related to the transaction will be included in
899
+ # {CommitResponse}. Default value is `false`
900
+ #
901
+ # @return [Time, CommitResponse] The timestamp at which the operation
902
+ # committed. If commit options are set it returns {CommitResponse}.
869
903
  #
870
904
  # @example
871
905
  # require "google/cloud/spanner"
@@ -877,9 +911,24 @@ module Google
877
911
  # db.insert "users", [{ id: 1, name: "Charlie", active: false },
878
912
  # { id: 2, name: "Harvey", active: true }]
879
913
  #
880
- def insert table, *rows
914
+ # @example Get commit stats
915
+ # require "google/cloud/spanner"
916
+ #
917
+ # spanner = Google::Cloud::Spanner.new
918
+ #
919
+ # db = spanner.client "my-instance", "my-database"
920
+ #
921
+ # records = [{ id: 1, name: "Charlie", active: false },
922
+ # { id: 2, name: "Harvey", active: true }]
923
+ # commit_options = { return_commit_stats: true }
924
+ # commit_resp = db.insert "users", records, commit_options: commit_options
925
+ #
926
+ # puts commit_resp.timestamp
927
+ # puts commit_resp.stats.mutation_count
928
+ #
929
+ def insert table, rows, commit_options: nil
881
930
  @pool.with_session do |session|
882
- session.insert table, rows
931
+ session.insert table, rows, commit_options: commit_options
883
932
  end
884
933
  end
885
934
 
@@ -920,7 +969,16 @@ module Google
920
969
  # See [Data
921
970
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
922
971
  #
923
- # @return [Time] The timestamp at which the operation committed.
972
+ # @param [Hash] commit_options A hash of commit options.
973
+ # e.g., return_commit_stats. Commit options are optional.
974
+ # The following options can be provided:
975
+ #
976
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
977
+ # then statistics related to the transaction will be included in
978
+ # {CommitResponse}. Default value is `false`
979
+ #
980
+ # @return [Time, CommitResponse] The timestamp at which the operation
981
+ # committed. If commit options are set it returns {CommitResponse}.
924
982
  #
925
983
  # @example
926
984
  # require "google/cloud/spanner"
@@ -932,9 +990,24 @@ module Google
932
990
  # db.update "users", [{ id: 1, name: "Charlie", active: false },
933
991
  # { id: 2, name: "Harvey", active: true }]
934
992
  #
935
- def update table, *rows
993
+ # @example Get commit stats
994
+ # require "google/cloud/spanner"
995
+ #
996
+ # spanner = Google::Cloud::Spanner.new
997
+ #
998
+ # db = spanner.client "my-instance", "my-database"
999
+ #
1000
+ # records = [{ id: 1, name: "Charlie", active: false },
1001
+ # { id: 2, name: "Harvey", active: true }]
1002
+ # commit_options = { return_commit_stats: true }
1003
+ # commit_resp = db.update "users", records, commit_options: commit_options
1004
+ #
1005
+ # puts commit_resp.timestamp
1006
+ # puts commit_resp.stats.mutation_count
1007
+ #
1008
+ def update table, rows, commit_options: nil
936
1009
  @pool.with_session do |session|
937
- session.update table, rows
1010
+ session.update table, rows, commit_options: commit_options
938
1011
  end
939
1012
  end
940
1013
 
@@ -977,7 +1050,16 @@ module Google
977
1050
  # See [Data
978
1051
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
979
1052
  #
980
- # @return [Time] The timestamp at which the operation committed.
1053
+ # @param [Hash] commit_options A hash of commit options.
1054
+ # e.g., return_commit_stats. Commit options are optional.
1055
+ # The following options can be provided:
1056
+ #
1057
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
1058
+ # then statistics related to the transaction will be included in
1059
+ # {CommitResponse}. Default value is `false`
1060
+ #
1061
+ # @return [Time, CommitResponse] The timestamp at which the operation
1062
+ # committed. If commit options are set it returns {CommitResponse}.
981
1063
  #
982
1064
  # @example
983
1065
  # require "google/cloud/spanner"
@@ -989,9 +1071,24 @@ module Google
989
1071
  # db.replace "users", [{ id: 1, name: "Charlie", active: false },
990
1072
  # { id: 2, name: "Harvey", active: true }]
991
1073
  #
992
- def replace table, *rows
1074
+ # @example Get commit stats
1075
+ # require "google/cloud/spanner"
1076
+ #
1077
+ # spanner = Google::Cloud::Spanner.new
1078
+ #
1079
+ # db = spanner.client "my-instance", "my-database"
1080
+ #
1081
+ # records = [{ id: 1, name: "Charlie", active: false },
1082
+ # { id: 2, name: "Harvey", active: true }]
1083
+ # commit_options = { return_commit_stats: true }
1084
+ # commit_resp = db.replace "users", records, commit_options: commit_options
1085
+ #
1086
+ # puts commit_resp.timestamp
1087
+ # puts commit_resp.stats.mutation_count
1088
+ #
1089
+ def replace table, rows, commit_options: nil
993
1090
  @pool.with_session do |session|
994
- session.replace table, rows
1091
+ session.replace table, rows, commit_options: commit_options
995
1092
  end
996
1093
  end
997
1094
 
@@ -1015,6 +1112,14 @@ module Google
1015
1112
  # @param [Object, Array<Object>] keys A single, or list of keys or key
1016
1113
  # ranges to match returned data to. Values should have exactly as many
1017
1114
  # elements as there are columns in the primary key.
1115
+ # @param [Hash] commit_options A hash of commit options.
1116
+ # e.g., return_commit_stats. Commit options are optional.
1117
+ # The following options can be provided:
1118
+ #
1119
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
1120
+ # then statistics related to the transaction will be included in
1121
+ # {CommitResponse}. Default value is `false`
1122
+ #
1018
1123
  # @param [Hash] call_options A hash of values to specify the custom
1019
1124
  # call options, e.g., timeout, retries, etc. Call options are
1020
1125
  # optional. The following settings can be provided:
@@ -1029,7 +1134,8 @@ module Google
1029
1134
  # * `:retry_codes` (`Array<String>`) - The error codes that should
1030
1135
  # trigger a retry.
1031
1136
  #
1032
- # @return [Time] The timestamp at which the operation committed.
1137
+ # @return [Time, CommitResponse] The timestamp at which the operation
1138
+ # committed. If commit options are set it returns {CommitResponse}.
1033
1139
  #
1034
1140
  # @example
1035
1141
  # require "google/cloud/spanner"
@@ -1040,9 +1146,23 @@ module Google
1040
1146
  #
1041
1147
  # db.delete "users", [1, 2, 3]
1042
1148
  #
1043
- def delete table, keys = [], call_options: nil
1149
+ # @example Get commit stats
1150
+ # require "google/cloud/spanner"
1151
+ #
1152
+ # spanner = Google::Cloud::Spanner.new
1153
+ #
1154
+ # db = spanner.client "my-instance", "my-database"
1155
+ #
1156
+ # commit_options = { return_commit_stats: true }
1157
+ # commit_resp = db.delete "users", [1, 2, 3], commit_options: commit_options
1158
+ #
1159
+ # puts commit_resp.timestamp
1160
+ # puts commit_resp.stats.mutation_count
1161
+ #
1162
+ def delete table, keys = [], commit_options: nil, call_options: nil
1044
1163
  @pool.with_session do |session|
1045
- session.delete table, keys, call_options: call_options
1164
+ session.delete table, keys, commit_options: commit_options,
1165
+ call_options: call_options
1046
1166
  end
1047
1167
  end
1048
1168
 
@@ -1061,6 +1181,14 @@ module Google
1061
1181
  # this method may be appropriate for latency sensitive and/or high
1062
1182
  # throughput blind changes.
1063
1183
  #
1184
+ # @param [Hash] commit_options A hash of commit options.
1185
+ # e.g., return_commit_stats. Commit options are optional.
1186
+ # The following options can be provided:
1187
+ #
1188
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
1189
+ # then statistics related to the transaction will be included in
1190
+ # {CommitResponse}. Default value is `false`
1191
+ #
1064
1192
  # @param [Hash] call_options A hash of values to specify the custom
1065
1193
  # call options, e.g., timeout, retries, etc. Call options are
1066
1194
  # optional. The following settings can be provided:
@@ -1078,7 +1206,8 @@ module Google
1078
1206
  # @yield [commit] The block for mutating the data.
1079
1207
  # @yieldparam [Google::Cloud::Spanner::Commit] commit The Commit object.
1080
1208
  #
1081
- # @return [Time] The timestamp at which the operation committed.
1209
+ # @return [Time, CommitResponse] The timestamp at which the operation
1210
+ # committed. If commit options are set it returns {CommitResponse}.
1082
1211
  #
1083
1212
  # @example
1084
1213
  # require "google/cloud/spanner"
@@ -1092,15 +1221,34 @@ module Google
1092
1221
  # c.insert "users", [{ id: 2, name: "Harvey", active: true }]
1093
1222
  # end
1094
1223
  #
1095
- def commit call_options: nil, &block
1224
+ # @example Get commit stats
1225
+ # require "google/cloud/spanner"
1226
+ #
1227
+ # spanner = Google::Cloud::Spanner.new
1228
+ #
1229
+ # db = spanner.client "my-instance", "my-database"
1230
+ #
1231
+ # commit_options = { return_commit_stats: true }
1232
+ # commit_resp = db.commit commit_options: commit_options do |c|
1233
+ # c.update "users", [{ id: 1, name: "Charlie", active: false }]
1234
+ # c.insert "users", [{ id: 2, name: "Harvey", active: true }]
1235
+ # end
1236
+ #
1237
+ # puts commit_resp.timestamp
1238
+ # puts commit_resp.stats.mutation_count
1239
+ #
1240
+ def commit commit_options: nil, call_options: nil, &block
1096
1241
  raise ArgumentError, "Must provide a block" unless block_given?
1097
1242
 
1098
1243
  @pool.with_session do |session|
1099
- session.commit(call_options: call_options, &block)
1244
+ session.commit(
1245
+ commit_options: commit_options, call_options: call_options, &block
1246
+ )
1100
1247
  end
1101
1248
  end
1102
1249
 
1103
1250
  # rubocop:disable Metrics/AbcSize
1251
+ # rubocop:disable Metrics/BlockLength
1104
1252
  # rubocop:disable Metrics/MethodLength
1105
1253
 
1106
1254
  ##
@@ -1119,6 +1267,14 @@ module Google
1119
1267
  #
1120
1268
  # @param [Numeric] deadline The total amount of time in seconds the
1121
1269
  # transaction has to succeed. The default is `120`.
1270
+ # @param [Hash] commit_options A hash of commit options.
1271
+ # e.g., return_commit_stats. Commit options are optional.
1272
+ # The following options can be provided:
1273
+ #
1274
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
1275
+ # then statistics related to the transaction will be included in
1276
+ # {CommitResponse}. Default value is `false`
1277
+ #
1122
1278
  # @param [Hash] call_options A hash of values to specify the custom
1123
1279
  # call options, e.g., timeout, retries, etc. Call options are
1124
1280
  # optional. The following settings can be provided:
@@ -1137,7 +1293,8 @@ module Google
1137
1293
  # @yieldparam [Google::Cloud::Spanner::Transaction] transaction The
1138
1294
  # Transaction object.
1139
1295
  #
1140
- # @return [Time] The timestamp at which the transaction committed.
1296
+ # @return [Time, CommitResponse] The timestamp at which the operation
1297
+ # committed. If commit options are set it returns {CommitResponse}.
1141
1298
  #
1142
1299
  # @example
1143
1300
  # require "google/cloud/spanner"
@@ -1173,7 +1330,28 @@ module Google
1173
1330
  # end
1174
1331
  # end
1175
1332
  #
1176
- def transaction deadline: 120, call_options: nil
1333
+ # @example Get commit stats
1334
+ # require "google/cloud/spanner"
1335
+ #
1336
+ # spanner = Google::Cloud::Spanner.new
1337
+ # db = spanner.client "my-instance", "my-database"
1338
+ #
1339
+ # commit_options = { return_commit_stats: true }
1340
+ # commit_resp = db.transaction commit_options: commit_options do |tx|
1341
+ # results = tx.execute_query "SELECT * FROM users"
1342
+ #
1343
+ # results.rows.each do |row|
1344
+ # puts "User #{row[:id]} is #{row[:name]}"
1345
+ # end
1346
+ #
1347
+ # tx.update "users", [{ id: 1, name: "Charlie", active: false }]
1348
+ # tx.insert "users", [{ id: 2, name: "Harvey", active: true }]
1349
+ # end
1350
+ #
1351
+ # puts commit_resp.timestamp
1352
+ # puts commit_resp.stats.mutation_count
1353
+ #
1354
+ def transaction deadline: 120, commit_options: nil, call_options: nil
1177
1355
  ensure_service!
1178
1356
  unless Thread.current[:transaction_id].nil?
1179
1357
  raise "Nested transactions are not allowed"
@@ -1189,8 +1367,11 @@ module Google
1189
1367
  yield tx
1190
1368
  commit_resp = @project.service.commit \
1191
1369
  tx.session.path, tx.mutations,
1192
- transaction_id: tx.transaction_id, call_options: call_options
1193
- return Convert.timestamp_to_time commit_resp.commit_timestamp
1370
+ transaction_id: tx.transaction_id,
1371
+ commit_options: commit_options,
1372
+ call_options: call_options
1373
+ resp = CommitResponse.from_grpc commit_resp
1374
+ commit_options ? resp : resp.timestamp
1194
1375
  rescue GRPC::Aborted, Google::Cloud::AbortedError => err
1195
1376
  # Re-raise if deadline has passed
1196
1377
  if current_time - start_time > deadline
@@ -1218,6 +1399,7 @@ module Google
1218
1399
  end
1219
1400
 
1220
1401
  # rubocop:enable Metrics/AbcSize
1402
+ # rubocop:enable Metrics/BlockLength
1221
1403
  # rubocop:enable Metrics/MethodLength
1222
1404
 
1223
1405
  ##
@@ -0,0 +1,87 @@
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
+ require "google/cloud/spanner/commit_response/commit_stats"
17
+
18
+ module Google
19
+ module Cloud
20
+ module Spanner
21
+ ##
22
+ # CommitResponse is a timestamp at which the transaction committed
23
+ # with additional attributes of commit stats.
24
+ #
25
+ # @example
26
+ # require "google/cloud/spanner"
27
+ #
28
+ # spanner = Google::Cloud::Spanner.new
29
+ #
30
+ # db = spanner.client "my-instance", "my-database"
31
+ #
32
+ # timestamp = db.commit do |c|
33
+ # c.update "users", [{ id: 1, name: "Charlie", active: false }]
34
+ # c.insert "users", [{ id: 2, name: "Harvey", active: true }]
35
+ # end
36
+ #
37
+ # puts timestamp
38
+ #
39
+ # @example With commit stats.
40
+ # require "google/cloud/spanner"
41
+ #
42
+ # spanner = Google::Cloud::Spanner.new
43
+ #
44
+ # db = spanner.client "my-instance", "my-database"
45
+ #
46
+ # commit_options = { return_commit_stats: true }
47
+ # commit_resp = db.commit commit_options: commit_options do |c|
48
+ # c.update "users", [{ id: 1, name: "Charlie", active: false }]
49
+ # c.insert "users", [{ id: 2, name: "Harvey", active: true }]
50
+ # end
51
+ #
52
+ # puts commit_resp.timestamp
53
+ # puts commit_resp.stats.mutation_count
54
+ #
55
+ class CommitResponse
56
+ ##
57
+ # @private Creates a new CommitResponse instance.
58
+ def initialize grpc
59
+ @grpc = grpc
60
+ end
61
+
62
+ ##
63
+ # The timestamp at which the transaction committed.
64
+ # @return [Time]
65
+ def timestamp
66
+ Convert.timestamp_to_time @grpc.commit_timestamp
67
+ end
68
+
69
+ ##
70
+ # Additional statistics about a commit.
71
+ # @return [CommitStats, nil] Commit stats or nil if not stats not
72
+ # present.
73
+ def stats
74
+ CommitStats.from_grpc @grpc.commit_stats if @grpc.commit_stats
75
+ end
76
+
77
+ ##
78
+ # @private
79
+ # Creates a new Commit responsee instance from a
80
+ # `Google::Cloud::Spanner::V1::CommitResponse`.
81
+ def self.from_grpc grpc
82
+ new grpc
83
+ end
84
+ end
85
+ end
86
+ end
87
+ end
@@ -0,0 +1,51 @@
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
+ require "google/cloud/spanner/convert"
17
+
18
+ module Google
19
+ module Cloud
20
+ module Spanner
21
+ class CommitResponse
22
+ ##
23
+ # # CommitStats
24
+ #
25
+ # Statistical information of a transaction commit.
26
+ #
27
+ class CommitStats
28
+ ##
29
+ # @private Creates a new CommitStats instance.
30
+ def initialize grpc
31
+ @grpc = grpc
32
+ end
33
+
34
+ # The total number of the mutations for the transaction.
35
+ # @return [Integer]
36
+ def mutation_count
37
+ @grpc.mutation_count
38
+ end
39
+
40
+ ##
41
+ # @private
42
+ # Creates a new CommitStats instance from a
43
+ # `Google::Cloud::Spanner::V1::CommitResponse::CommitStats`.
44
+ def self.from_grpc grpc
45
+ new grpc
46
+ end
47
+ end
48
+ end
49
+ end
50
+ end
51
+ end
@@ -397,7 +397,7 @@ module Google
397
397
  end
398
398
 
399
399
  def commit session_name, mutations = [], transaction_id: nil,
400
- call_options: nil
400
+ commit_options: nil, call_options: nil
401
401
  tx_opts = nil
402
402
  if transaction_id.nil?
403
403
  tx_opts = V1::TransactionOptions.new(
@@ -410,6 +410,11 @@ module Google
410
410
  session: session_name, transaction_id: transaction_id,
411
411
  single_use_transaction: tx_opts, mutations: mutations
412
412
  }
413
+
414
+ if commit_options
415
+ request[:return_commit_stats] = commit_options[:return_commit_stats]
416
+ end
417
+
413
418
  service.commit request, opts
414
419
  end
415
420
 
@@ -16,6 +16,7 @@
16
16
  require "google/cloud/spanner/data"
17
17
  require "google/cloud/spanner/results"
18
18
  require "google/cloud/spanner/commit"
19
+ require "google/cloud/spanner/commit_response"
19
20
  require "google/cloud/spanner/batch_update"
20
21
 
21
22
  module Google
@@ -484,6 +485,15 @@ module Google
484
485
  # @param [String] transaction_id The identifier of previously-started
485
486
  # transaction to be used instead of starting a new transaction.
486
487
  # Optional.
488
+ # @param [Hash] commit_options A hash of commit options.
489
+ # e.g., return_commit_stats. Commit options are optional.
490
+ # The following options can be provided:
491
+ #
492
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
493
+ # then statistics related to the transaction will be included in
494
+ # {CommitResponse}. Default value is `false`
495
+ #
496
+ # transaction. Default it is `false`.
487
497
  # @param [Hash] call_options A hash of values to specify the custom
488
498
  # call options, e.g., timeout, retries, etc. Call options are
489
499
  # optional. The following settings can be provided:
@@ -501,7 +511,8 @@ module Google
501
511
  # @yield [commit] The block for mutating the data.
502
512
  # @yieldparam [Google::Cloud::Spanner::Commit] commit The Commit object.
503
513
  #
504
- # @return [Time] The timestamp at which the operation committed.
514
+ # @return [Time, CommitResponse] The timestamp at which the operation
515
+ # committed. If commit options are set it returns {CommitResponse}.
505
516
  #
506
517
  # @example
507
518
  # require "google/cloud/spanner"
@@ -515,15 +526,33 @@ module Google
515
526
  # c.insert "users", [{ id: 2, name: "Harvey", active: true }]
516
527
  # end
517
528
  #
518
- def commit transaction_id: nil, call_options: nil
529
+ # @example Get commit stats
530
+ # require "google/cloud/spanner"
531
+ #
532
+ # spanner = Google::Cloud::Spanner.new
533
+ #
534
+ # db = spanner.client "my-instance", "my-database"
535
+ #
536
+ # commit_options = { return_commit_stats: true }
537
+ # commit_resp = db.commit commit_options: commit_options do |c|
538
+ # c.update "users", [{ id: 1, name: "Charlie", active: false }]
539
+ # c.insert "users", [{ id: 2, name: "Harvey", active: true }]
540
+ # end
541
+ #
542
+ # puts commit_resp.timestamp
543
+ # puts commit_resp.stats.mutation_count
544
+ #
545
+ def commit transaction_id: nil, commit_options: nil, call_options: nil
519
546
  ensure_service!
520
547
  commit = Commit.new
521
548
  yield commit
522
549
  commit_resp = service.commit path, commit.mutations,
523
550
  transaction_id: transaction_id,
551
+ commit_options: commit_options,
524
552
  call_options: call_options
525
553
  @last_updated_at = Time.now
526
- Convert.timestamp_to_time commit_resp.commit_timestamp
554
+ resp = CommitResponse.from_grpc commit_resp
555
+ commit_options ? resp : resp.timestamp
527
556
  end
528
557
 
529
558
  ##
@@ -552,6 +581,15 @@ module Google
552
581
  #
553
582
  # See [Data
554
583
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
584
+ #
585
+ # @param [Hash] commit_options A hash of commit options.
586
+ # e.g., return_commit_stats. Commit options are optional.
587
+ # The following options can be provided:
588
+ #
589
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
590
+ # then statistics related to the transaction will be included in
591
+ # {CommitResponse}. Default value is `false`
592
+ #
555
593
  # @param [Hash] call_options A hash of values to specify the custom
556
594
  # call options, e.g., timeout, retries, etc. Call options are
557
595
  # optional. The following settings can be provided:
@@ -566,7 +604,8 @@ module Google
566
604
  # * `:retry_codes` (`Array<String>`) - The error codes that should
567
605
  # trigger a retry.
568
606
  #
569
- # @return [Time] The timestamp at which the operation committed.
607
+ # @return [Time, CommitResponse] The timestamp at which the operation
608
+ # committed. If commit options are set it returns {CommitResponse}.
570
609
  #
571
610
  # @example
572
611
  # require "google/cloud/spanner"
@@ -578,8 +617,28 @@ module Google
578
617
  # db.upsert "users", [{ id: 1, name: "Charlie", active: false },
579
618
  # { id: 2, name: "Harvey", active: true }]
580
619
  #
581
- def upsert table, *rows, transaction_id: nil, call_options: nil
582
- opts = { transaction_id: transaction_id, call_options: call_options }
620
+ # @example Get commit stats
621
+ # require "google/cloud/spanner"
622
+ #
623
+ # spanner = Google::Cloud::Spanner.new
624
+ #
625
+ # db = spanner.client "my-instance", "my-database"
626
+ #
627
+ # records = [{ id: 1, name: "Charlie", active: false },
628
+ # { id: 2, name: "Harvey", active: true }]
629
+ # commit_options = { return_commit_stats: true }
630
+ # commit_resp = db.upsert "users", records, commit_options: commit_options
631
+ #
632
+ # puts commit_resp.timestamp
633
+ # puts commit_resp.stats.mutation_count
634
+ #
635
+ def upsert table, *rows, transaction_id: nil, commit_options: nil,
636
+ call_options: nil
637
+ opts = {
638
+ transaction_id: transaction_id,
639
+ commit_options: commit_options,
640
+ call_options: call_options
641
+ }
583
642
  commit opts do |c|
584
643
  c.upsert table, rows
585
644
  end
@@ -611,6 +670,15 @@ module Google
611
670
  #
612
671
  # See [Data
613
672
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
673
+ #
674
+ # @param [Hash] commit_options A hash of commit options.
675
+ # e.g., return_commit_stats. Commit options are optional.
676
+ # The following options can be provided:
677
+ #
678
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
679
+ # then statistics related to the transaction will be included in
680
+ # {CommitResponse}. Default value is `false`
681
+ #
614
682
  # @param [Hash] call_options A hash of values to specify the custom
615
683
  # call options, e.g., timeout, retries, etc. Call options are
616
684
  # optional. The following settings can be provided:
@@ -625,7 +693,8 @@ module Google
625
693
  # * `:retry_codes` (`Array<String>`) - The error codes that should
626
694
  # trigger a retry.
627
695
  #
628
- # @return [Time] The timestamp at which the operation committed.
696
+ # @return [Time, CommitResponse] The timestamp at which the operation
697
+ # committed. If commit options are set it returns {CommitResponse}.
629
698
  #
630
699
  # @example
631
700
  # require "google/cloud/spanner"
@@ -637,8 +706,28 @@ module Google
637
706
  # db.insert "users", [{ id: 1, name: "Charlie", active: false },
638
707
  # { id: 2, name: "Harvey", active: true }]
639
708
  #
640
- def insert table, *rows, transaction_id: nil, call_options: nil
641
- opts = { transaction_id: transaction_id, call_options: call_options }
709
+ # @example Get commit stats
710
+ # require "google/cloud/spanner"
711
+ #
712
+ # spanner = Google::Cloud::Spanner.new
713
+ #
714
+ # db = spanner.client "my-instance", "my-database"
715
+ #
716
+ # records = [{ id: 1, name: "Charlie", active: false },
717
+ # { id: 2, name: "Harvey", active: true }]
718
+ # commit_options = { return_commit_stats: true }
719
+ # commit_resp = db.insert "users", records, commit_options: commit_options
720
+ #
721
+ # puts commit_resp.timestamp
722
+ # puts commit_resp.stats.mutation_count
723
+ #
724
+ def insert table, *rows, transaction_id: nil, commit_options: nil,
725
+ call_options: nil
726
+ opts = {
727
+ transaction_id: transaction_id,
728
+ commit_options: commit_options,
729
+ call_options: call_options
730
+ }
642
731
  commit opts do |c|
643
732
  c.insert table, rows
644
733
  end
@@ -669,6 +758,15 @@ module Google
669
758
  #
670
759
  # See [Data
671
760
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
761
+ #
762
+ # @param [Hash] commit_options A hash of commit options.
763
+ # e.g., return_commit_stats. Commit options are optional.
764
+ # The following options can be provided:
765
+ #
766
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
767
+ # then statistics related to the transaction will be included in
768
+ # {CommitResponse}. Default value is `false`
769
+ #
672
770
  # @param [Hash] call_options A hash of values to specify the custom
673
771
  # call options, e.g., timeout, retries, etc. Call options are
674
772
  # optional. The following settings can be provided:
@@ -683,7 +781,8 @@ module Google
683
781
  # * `:retry_codes` (`Array<String>`) - The error codes that should
684
782
  # trigger a retry.
685
783
  #
686
- # @return [Time] The timestamp at which the operation committed.
784
+ # @return [Time, CommitResponse] The timestamp at which the operation
785
+ # committed. If commit options are set it returns {CommitResponse}.
687
786
  #
688
787
  # @example
689
788
  # require "google/cloud/spanner"
@@ -695,8 +794,28 @@ module Google
695
794
  # db.update "users", [{ id: 1, name: "Charlie", active: false },
696
795
  # { id: 2, name: "Harvey", active: true }]
697
796
  #
698
- def update table, *rows, transaction_id: nil, call_options: nil
699
- opts = { transaction_id: transaction_id, call_options: call_options }
797
+ # @example Get commit stats
798
+ # require "google/cloud/spanner"
799
+ #
800
+ # spanner = Google::Cloud::Spanner.new
801
+ #
802
+ # db = spanner.client "my-instance", "my-database"
803
+ #
804
+ # records = [{ id: 1, name: "Charlie", active: false },
805
+ # { id: 2, name: "Harvey", active: true }]
806
+ # commit_options = { return_commit_stats: true }
807
+ # commit_resp = db.update "users", records, commit_options: commit_options
808
+ #
809
+ # puts commit_resp.timestamp
810
+ # puts commit_resp.stats.mutation_count
811
+ #
812
+ def update table, *rows, transaction_id: nil, commit_options: nil,
813
+ call_options: nil
814
+ opts = {
815
+ transaction_id: transaction_id,
816
+ commit_options: commit_options,
817
+ call_options: call_options
818
+ }
700
819
  commit opts do |c|
701
820
  c.update table, rows
702
821
  end
@@ -729,6 +848,15 @@ module Google
729
848
  #
730
849
  # See [Data
731
850
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
851
+ #
852
+ # @param [Hash] commit_options A hash of commit options.
853
+ # e.g., return_commit_stats. Commit options are optional.
854
+ # The following options can be provided:
855
+ #
856
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
857
+ # then statistics related to the transaction will be included in
858
+ # {CommitResponse}. Default value is `false`.
859
+ #
732
860
  # @param [Hash] call_options A hash of values to specify the custom
733
861
  # call options, e.g., timeout, retries, etc. Call options are
734
862
  # optional. The following settings can be provided:
@@ -743,7 +871,8 @@ module Google
743
871
  # * `:retry_codes` (`Array<String>`) - The error codes that should
744
872
  # trigger a retry.
745
873
  #
746
- # @return [Time] The timestamp at which the operation committed.
874
+ # @return [Time, CommitResponse] The timestamp at which the operation
875
+ # committed. If commit options are set it returns {CommitResponse}.
747
876
  #
748
877
  # @example
749
878
  # require "google/cloud/spanner"
@@ -755,8 +884,28 @@ module Google
755
884
  # db.replace "users", [{ id: 1, name: "Charlie", active: false },
756
885
  # { id: 2, name: "Harvey", active: true }]
757
886
  #
758
- def replace table, *rows, transaction_id: nil, call_options: nil
759
- opts = { transaction_id: transaction_id, call_options: call_options }
887
+ # @example Get commit stats
888
+ # require "google/cloud/spanner"
889
+ #
890
+ # spanner = Google::Cloud::Spanner.new
891
+ #
892
+ # db = spanner.client "my-instance", "my-database"
893
+ #
894
+ # records = [{ id: 1, name: "Charlie", active: false },
895
+ # { id: 2, name: "Harvey", active: true }]
896
+ # commit_options = { return_commit_stats: true }
897
+ # commit_resp = db.replace "users", records, commit_options: commit_options
898
+ #
899
+ # puts commit_resp.timestamp
900
+ # puts commit_resp.stats.mutation_count
901
+ #
902
+ def replace table, *rows, transaction_id: nil, commit_options: nil,
903
+ call_options: nil
904
+ opts = {
905
+ transaction_id: transaction_id,
906
+ commit_options: commit_options,
907
+ call_options: call_options
908
+ }
760
909
  commit opts do |c|
761
910
  c.replace table, rows
762
911
  end
@@ -771,6 +920,14 @@ module Google
771
920
  # @param [Object, Array<Object>] keys A single, or list of keys or key
772
921
  # ranges to match returned data to. Values should have exactly as many
773
922
  # elements as there are columns in the primary key.
923
+ # @param [Hash] commit_options A hash of commit options.
924
+ # e.g., return_commit_stats. Commit options are optional.
925
+ # The following options can be provided:
926
+ #
927
+ # * `:return_commit_stats` (Boolean) A boolean value. If `true`,
928
+ # then statistics related to the transaction will be included in
929
+ # {CommitResponse}. Default value is `false`
930
+ #
774
931
  # @param [Hash] call_options A hash of values to specify the custom
775
932
  # call options, e.g., timeout, retries, etc. Call options are
776
933
  # optional. The following settings can be provided:
@@ -785,7 +942,8 @@ module Google
785
942
  # * `:retry_codes` (`Array<String>`) - The error codes that should
786
943
  # trigger a retry.
787
944
  #
788
- # @return [Time] The timestamp at which the operation committed.
945
+ # @return [Time, CommitResponse] The timestamp at which the operation
946
+ # committed. If commit options are set it returns {CommitResponse}.
789
947
  #
790
948
  # @example
791
949
  # require "google/cloud/spanner"
@@ -796,8 +954,26 @@ module Google
796
954
  #
797
955
  # db.delete "users", [1, 2, 3]
798
956
  #
799
- def delete table, keys = [], transaction_id: nil, call_options: nil
800
- opts = { transaction_id: transaction_id, call_options: call_options }
957
+ # @example Get commit stats
958
+ # require "google/cloud/spanner"
959
+ #
960
+ # spanner = Google::Cloud::Spanner.new
961
+ #
962
+ # db = spanner.client "my-instance", "my-database"
963
+ #
964
+ # commit_options = { return_commit_stats: true }
965
+ # commit_resp = db.delete "users", [1,2,3], commit_options: commit_options
966
+ #
967
+ # puts commit_resp.timestamp
968
+ # puts commit_resp.stats.mutation_count
969
+ #
970
+ def delete table, keys = [], transaction_id: nil, commit_options: nil,
971
+ call_options: nil
972
+ opts = {
973
+ transaction_id: transaction_id,
974
+ commit_options: commit_options,
975
+ call_options: call_options
976
+ }
801
977
  commit opts do |c|
802
978
  c.delete table, keys
803
979
  end
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module Spanner
19
- VERSION = "2.2.0".freeze
19
+ VERSION = "2.3.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.2.0
4
+ version: 2.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Mike Moore
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2020-09-15 00:00:00.000000000 Z
12
+ date: 2021-02-09 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: google-cloud-core
@@ -282,6 +282,8 @@ files:
282
282
  - lib/google/cloud/spanner/client.rb
283
283
  - lib/google/cloud/spanner/column_value.rb
284
284
  - lib/google/cloud/spanner/commit.rb
285
+ - lib/google/cloud/spanner/commit_response.rb
286
+ - lib/google/cloud/spanner/commit_response/commit_stats.rb
285
287
  - lib/google/cloud/spanner/convert.rb
286
288
  - lib/google/cloud/spanner/credentials.rb
287
289
  - lib/google/cloud/spanner/data.rb
@@ -329,7 +331,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
329
331
  - !ruby/object:Gem::Version
330
332
  version: '0'
331
333
  requirements: []
332
- rubygems_version: 3.1.4
334
+ rubygems_version: 3.2.6
333
335
  signing_key:
334
336
  specification_version: 4
335
337
  summary: API Client library for Google Cloud Spanner API