google-cloud-spanner 1.16.1 → 2.3.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (108) hide show
  1. checksums.yaml +4 -4
  2. data/AUTHENTICATION.md +1 -1
  3. data/CHANGELOG.md +58 -0
  4. data/CONTRIBUTING.md +6 -6
  5. data/TROUBLESHOOTING.md +0 -6
  6. data/lib/google-cloud-spanner.rb +11 -13
  7. data/lib/google/cloud/spanner.rb +13 -13
  8. data/lib/google/cloud/spanner/admin/database/credentials.rb +2 -2
  9. data/lib/google/cloud/spanner/admin/instance/credentials.rb +2 -2
  10. data/lib/google/cloud/spanner/backup.rb +1 -1
  11. data/lib/google/cloud/spanner/backup/job.rb +2 -2
  12. data/lib/google/cloud/spanner/backup/job/list.rb +2 -2
  13. data/lib/google/cloud/spanner/backup/list.rb +1 -2
  14. data/lib/google/cloud/spanner/backup/restore/job.rb +2 -2
  15. data/lib/google/cloud/spanner/batch_client.rb +2 -2
  16. data/lib/google/cloud/spanner/batch_snapshot.rb +120 -23
  17. data/lib/google/cloud/spanner/batch_update.rb +1 -1
  18. data/lib/google/cloud/spanner/client.rb +388 -47
  19. data/lib/google/cloud/spanner/commit.rb +14 -14
  20. data/lib/google/cloud/spanner/commit_response.rb +87 -0
  21. data/lib/google/cloud/spanner/commit_response/commit_stats.rb +51 -0
  22. data/lib/google/cloud/spanner/convert.rb +16 -7
  23. data/lib/google/cloud/spanner/credentials.rb +2 -2
  24. data/lib/google/cloud/spanner/data.rb +2 -2
  25. data/lib/google/cloud/spanner/database.rb +22 -22
  26. data/lib/google/cloud/spanner/database/backup_info.rb +1 -1
  27. data/lib/google/cloud/spanner/database/job.rb +3 -3
  28. data/lib/google/cloud/spanner/database/job/list.rb +2 -2
  29. data/lib/google/cloud/spanner/database/list.rb +1 -1
  30. data/lib/google/cloud/spanner/database/restore_info.rb +1 -1
  31. data/lib/google/cloud/spanner/fields.rb +8 -8
  32. data/lib/google/cloud/spanner/instance.rb +5 -12
  33. data/lib/google/cloud/spanner/instance/config.rb +1 -1
  34. data/lib/google/cloud/spanner/instance/config/list.rb +1 -1
  35. data/lib/google/cloud/spanner/instance/job.rb +2 -2
  36. data/lib/google/cloud/spanner/instance/list.rb +1 -1
  37. data/lib/google/cloud/spanner/partition.rb +4 -4
  38. data/lib/google/cloud/spanner/policy.rb +2 -2
  39. data/lib/google/cloud/spanner/results.rb +103 -24
  40. data/lib/google/cloud/spanner/service.rb +367 -349
  41. data/lib/google/cloud/spanner/session.rb +370 -39
  42. data/lib/google/cloud/spanner/snapshot.rb +60 -6
  43. data/lib/google/cloud/spanner/transaction.rb +116 -10
  44. data/lib/google/cloud/spanner/version.rb +1 -1
  45. metadata +20 -107
  46. data/lib/google/cloud/spanner/admin/database.rb +0 -149
  47. data/lib/google/cloud/spanner/admin/database/v1.rb +0 -147
  48. data/lib/google/cloud/spanner/admin/database/v1/credentials.rb +0 -46
  49. data/lib/google/cloud/spanner/admin/database/v1/database_admin_client.rb +0 -1513
  50. data/lib/google/cloud/spanner/admin/database/v1/database_admin_client_config.json +0 -111
  51. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/iam_policy.rb +0 -64
  52. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/options.rb +0 -33
  53. data/lib/google/cloud/spanner/admin/database/v1/doc/google/iam/v1/policy.rb +0 -151
  54. data/lib/google/cloud/spanner/admin/database/v1/doc/google/longrunning/operations.rb +0 -51
  55. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/any.rb +0 -131
  56. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/empty.rb +0 -29
  57. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/field_mask.rb +0 -222
  58. data/lib/google/cloud/spanner/admin/database/v1/doc/google/protobuf/timestamp.rb +0 -113
  59. data/lib/google/cloud/spanner/admin/database/v1/doc/google/rpc/status.rb +0 -39
  60. data/lib/google/cloud/spanner/admin/database/v1/doc/google/spanner/admin/database/v1/backup.rb +0 -325
  61. data/lib/google/cloud/spanner/admin/database/v1/doc/google/spanner/admin/database/v1/spanner_database_admin.rb +0 -368
  62. data/lib/google/cloud/spanner/admin/database/v1/doc/google/type/expr.rb +0 -45
  63. data/lib/google/cloud/spanner/admin/instance.rb +0 -164
  64. data/lib/google/cloud/spanner/admin/instance/v1.rb +0 -162
  65. data/lib/google/cloud/spanner/admin/instance/v1/credentials.rb +0 -46
  66. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/iam_policy.rb +0 -64
  67. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/options.rb +0 -33
  68. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/iam/v1/policy.rb +0 -151
  69. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/longrunning/operations.rb +0 -51
  70. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/any.rb +0 -131
  71. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/empty.rb +0 -29
  72. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/protobuf/field_mask.rb +0 -222
  73. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/rpc/status.rb +0 -39
  74. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/spanner/admin/instance/v1/spanner_instance_admin.rb +0 -334
  75. data/lib/google/cloud/spanner/admin/instance/v1/doc/google/type/expr.rb +0 -45
  76. data/lib/google/cloud/spanner/admin/instance/v1/instance_admin_client.rb +0 -975
  77. data/lib/google/cloud/spanner/admin/instance/v1/instance_admin_client_config.json +0 -76
  78. data/lib/google/cloud/spanner/v1.rb +0 -16
  79. data/lib/google/cloud/spanner/v1/credentials.rb +0 -42
  80. data/lib/google/cloud/spanner/v1/doc/google/protobuf/any.rb +0 -131
  81. data/lib/google/cloud/spanner/v1/doc/google/protobuf/duration.rb +0 -91
  82. data/lib/google/cloud/spanner/v1/doc/google/protobuf/empty.rb +0 -29
  83. data/lib/google/cloud/spanner/v1/doc/google/protobuf/struct.rb +0 -74
  84. data/lib/google/cloud/spanner/v1/doc/google/protobuf/timestamp.rb +0 -113
  85. data/lib/google/cloud/spanner/v1/doc/google/rpc/status.rb +0 -39
  86. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/keys.rb +0 -150
  87. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/mutation.rb +0 -95
  88. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb +0 -121
  89. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/result_set.rb +0 -190
  90. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/spanner.rb +0 -570
  91. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/transaction.rb +0 -432
  92. data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/type.rb +0 -112
  93. data/lib/google/cloud/spanner/v1/spanner_client.rb +0 -1485
  94. data/lib/google/cloud/spanner/v1/spanner_client_config.json +0 -121
  95. data/lib/google/spanner/admin/database/v1/backup_pb.rb +0 -98
  96. data/lib/google/spanner/admin/database/v1/common_pb.rb +0 -28
  97. data/lib/google/spanner/admin/database/v1/spanner_database_admin_pb.rb +0 -141
  98. data/lib/google/spanner/admin/database/v1/spanner_database_admin_services_pb.rb +0 -169
  99. data/lib/google/spanner/admin/instance/v1/spanner_instance_admin_pb.rb +0 -125
  100. data/lib/google/spanner/admin/instance/v1/spanner_instance_admin_services_pb.rb +0 -181
  101. data/lib/google/spanner/v1/keys_pb.rb +0 -34
  102. data/lib/google/spanner/v1/mutation_pb.rb +0 -39
  103. data/lib/google/spanner/v1/query_plan_pb.rb +0 -48
  104. data/lib/google/spanner/v1/result_set_pb.rb +0 -48
  105. data/lib/google/spanner/v1/spanner_pb.rb +0 -179
  106. data/lib/google/spanner/v1/spanner_services_pb.rb +0 -179
  107. data/lib/google/spanner/v1/transaction_pb.rb +0 -56
  108. data/lib/google/spanner/v1/type_pb.rb +0 -44
@@ -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
@@ -42,7 +43,7 @@ module Google
42
43
  #
43
44
  class Session
44
45
  ##
45
- # @private The Google::Spanner::V1::Session object
46
+ # @private The `Google::Cloud::Spanner::V1::Session` object
46
47
  attr_accessor :grpc
47
48
 
48
49
  ##
@@ -150,7 +151,7 @@ module Google
150
151
  # specified using a {Fields} object.
151
152
  #
152
153
  # Types are optional.
153
- # @param [Google::Spanner::V1::TransactionSelector] transaction The
154
+ # @param [Google::Cloud::Spanner::V1::TransactionSelector] transaction The
154
155
  # transaction selector value to send. Only used for single-use
155
156
  # transactions.
156
157
  # @param [Integer] seqno A per-transaction sequence number used to
@@ -162,6 +163,19 @@ module Google
162
163
  # * `:optimizer_version` (String) The version of optimizer to use.
163
164
  # Empty to use database default. "latest" to use the latest
164
165
  # available optimizer version.
166
+ # @param [Hash] call_options A hash of values to specify the custom
167
+ # call options, e.g., timeout, retries, etc. Call options are
168
+ # optional. The following settings can be provided:
169
+ #
170
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
171
+ # that overrides the default setting.
172
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
173
+ # setting of retry policy with the following keys:
174
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
175
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
176
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
177
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
178
+ # trigger a retry.
165
179
  #
166
180
  # @return [Google::Cloud::Spanner::Results] The results of the query
167
181
  # execution.
@@ -275,8 +289,32 @@ module Google
275
289
  # puts "User #{row[:id]} is #{row[:name]}"
276
290
  # end
277
291
  #
292
+ # @example Query using custom timeout and retry policy:
293
+ # require "google/cloud/spanner"
294
+ #
295
+ # spanner = Google::Cloud::Spanner.new
296
+ #
297
+ # db = spanner.client "my-instance", "my-database"
298
+ #
299
+ # timeout = 30.0
300
+ # retry_policy = {
301
+ # initial_delay: 0.25,
302
+ # max_delay: 32.0,
303
+ # multiplier: 1.3,
304
+ # retry_codes: ["UNAVAILABLE"]
305
+ # }
306
+ # call_options = { timeout: timeout, retry_policy: retry_policy }
307
+ #
308
+ # results = db.execute_query \
309
+ # "SELECT * FROM users", call_options: call_options
310
+ #
311
+ # results.rows.each do |row|
312
+ # puts "User #{row[:id]} is #{row[:name]}"
313
+ # end
314
+ #
278
315
  def execute_query sql, params: nil, types: nil, transaction: nil,
279
- partition_token: nil, seqno: nil, query_options: nil
316
+ partition_token: nil, seqno: nil, query_options: nil,
317
+ call_options: nil
280
318
  ensure_service!
281
319
  if query_options.nil?
282
320
  query_options = @query_options
@@ -289,7 +327,8 @@ module Google
289
327
  transaction: transaction,
290
328
  partition_token: partition_token,
291
329
  seqno: seqno,
292
- query_options: query_options
330
+ query_options: query_options,
331
+ call_options: call_options
293
332
  @last_updated_at = Time.now
294
333
  results
295
334
  end
@@ -297,11 +336,25 @@ module Google
297
336
  ##
298
337
  # Executes DML statements in a batch.
299
338
  #
300
- # @param [Google::Spanner::V1::TransactionSelector] transaction The
339
+ # @param [Google::Cloud::Spanner::V1::TransactionSelector] transaction The
301
340
  # transaction selector value to send. Only used for single-use
302
341
  # transactions.
303
342
  # @param [Integer] seqno A per-transaction sequence number used to
304
343
  # identify this request.
344
+ # @param [Hash] call_options A hash of values to specify the custom
345
+ # call options, e.g., timeout, retries, etc. Call options are
346
+ # optional. The following settings can be provided:
347
+ #
348
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
349
+ # that overrides the default setting.
350
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
351
+ # setting of retry policy with the following keys:
352
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
353
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
354
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
355
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
356
+ # trigger a retry.
357
+ #
305
358
  # @yield [batch_update] a batch update object
306
359
  # @yieldparam [Google::Cloud::Spanner::BatchUpdate] batch_update a batch
307
360
  # update object accepting DML statements and optional parameters and
@@ -316,7 +369,7 @@ module Google
316
369
  # @return [Array<Integer>] A list with the exact number of rows that
317
370
  # were modified for each DML statement.
318
371
  #
319
- def batch_update transaction, seqno
372
+ def batch_update transaction, seqno, call_options: nil
320
373
  ensure_service!
321
374
 
322
375
  raise ArgumentError, "block is required" unless block_given?
@@ -325,7 +378,8 @@ module Google
325
378
  yield batch
326
379
 
327
380
  results = service.execute_batch_dml path, transaction,
328
- batch.statements, seqno
381
+ batch.statements, seqno,
382
+ call_options: call_options
329
383
  @last_updated_at = Time.now
330
384
  results
331
385
  end
@@ -346,9 +400,22 @@ module Google
346
400
  # Optional.
347
401
  # @param [Integer] limit If greater than zero, no more than this number
348
402
  # of rows will be returned. The default is no limit.
349
- # @param [Google::Spanner::V1::TransactionSelector] transaction The
403
+ # @param [Google::Cloud::Spanner::V1::TransactionSelector] transaction The
350
404
  # transaction selector value to send. Only used for single-use
351
405
  # transactions.
406
+ # @param [Hash] call_options A hash of values to specify the custom
407
+ # call options, e.g., timeout, retries, etc. Call options are
408
+ # optional. The following settings can be provided:
409
+ #
410
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
411
+ # that overrides the default setting.
412
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
413
+ # setting of retry policy with the following keys:
414
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
415
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
416
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
417
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
418
+ # trigger a retry.
352
419
  #
353
420
  # @return [Google::Cloud::Spanner::Results] The results of the read
354
421
  # operation.
@@ -367,25 +434,28 @@ module Google
367
434
  # end
368
435
  #
369
436
  def read table, columns, keys: nil, index: nil, limit: nil,
370
- transaction: nil, partition_token: nil
437
+ transaction: nil, partition_token: nil, call_options: nil
371
438
  ensure_service!
372
439
 
373
440
  results = Results.read service, path, table, columns,
374
441
  keys: keys, index: index, limit: limit,
375
442
  transaction: transaction,
376
- partition_token: partition_token
443
+ partition_token: partition_token,
444
+ call_options: call_options
377
445
  @last_updated_at = Time.now
378
446
  results
379
447
  end
380
448
 
381
449
  def partition_query sql, transaction, params: nil, types: nil,
382
- partition_size_bytes: nil, max_partitions: nil
450
+ partition_size_bytes: nil, max_partitions: nil,
451
+ call_options: nil
383
452
  ensure_service!
384
453
 
385
454
  results = service.partition_query \
386
455
  path, sql, transaction, params: params, types: types,
387
456
  partition_size_bytes: partition_size_bytes,
388
- max_partitions: max_partitions
457
+ max_partitions: max_partitions,
458
+ call_options: call_options
389
459
 
390
460
  @last_updated_at = Time.now
391
461
 
@@ -394,14 +464,15 @@ module Google
394
464
 
395
465
  def partition_read table, columns, transaction, keys: nil,
396
466
  index: nil, partition_size_bytes: nil,
397
- max_partitions: nil
467
+ max_partitions: nil, call_options: nil
398
468
  ensure_service!
399
469
 
400
470
  results = service.partition_read \
401
471
  path, table, columns, transaction,
402
472
  keys: keys, index: index,
403
473
  partition_size_bytes: partition_size_bytes,
404
- max_partitions: max_partitions
474
+ max_partitions: max_partitions,
475
+ call_options: call_options
405
476
 
406
477
  @last_updated_at = Time.now
407
478
 
@@ -414,10 +485,34 @@ module Google
414
485
  # @param [String] transaction_id The identifier of previously-started
415
486
  # transaction to be used instead of starting a new transaction.
416
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`.
497
+ # @param [Hash] call_options A hash of values to specify the custom
498
+ # call options, e.g., timeout, retries, etc. Call options are
499
+ # optional. The following settings can be provided:
500
+ #
501
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
502
+ # that overrides the default setting.
503
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
504
+ # setting of retry policy with the following keys:
505
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
506
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
507
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
508
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
509
+ # trigger a retry.
510
+ #
417
511
  # @yield [commit] The block for mutating the data.
418
512
  # @yieldparam [Google::Cloud::Spanner::Commit] commit The Commit object.
419
513
  #
420
- # @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}.
421
516
  #
422
517
  # @example
423
518
  # require "google/cloud/spanner"
@@ -431,14 +526,33 @@ module Google
431
526
  # c.insert "users", [{ id: 2, name: "Harvey", active: true }]
432
527
  # end
433
528
  #
434
- def commit transaction_id: 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
435
546
  ensure_service!
436
547
  commit = Commit.new
437
548
  yield commit
438
549
  commit_resp = service.commit path, commit.mutations,
439
- transaction_id: transaction_id
550
+ transaction_id: transaction_id,
551
+ commit_options: commit_options,
552
+ call_options: call_options
440
553
  @last_updated_at = Time.now
441
- Convert.timestamp_to_time commit_resp.commit_timestamp
554
+ resp = CommitResponse.from_grpc commit_resp
555
+ commit_options ? resp : resp.timestamp
442
556
  end
443
557
 
444
558
  ##
@@ -468,7 +582,30 @@ module Google
468
582
  # See [Data
469
583
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
470
584
  #
471
- # @return [Time] The timestamp at which the operation committed.
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
+ #
593
+ # @param [Hash] call_options A hash of values to specify the custom
594
+ # call options, e.g., timeout, retries, etc. Call options are
595
+ # optional. The following settings can be provided:
596
+ #
597
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
598
+ # that overrides the default setting.
599
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
600
+ # setting of retry policy with the following keys:
601
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
602
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
603
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
604
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
605
+ # trigger a retry.
606
+ #
607
+ # @return [Time, CommitResponse] The timestamp at which the operation
608
+ # committed. If commit options are set it returns {CommitResponse}.
472
609
  #
473
610
  # @example
474
611
  # require "google/cloud/spanner"
@@ -480,8 +617,29 @@ module Google
480
617
  # db.upsert "users", [{ id: 1, name: "Charlie", active: false },
481
618
  # { id: 2, name: "Harvey", active: true }]
482
619
  #
483
- def upsert table, *rows, transaction_id: nil
484
- commit transaction_id: transaction_id do |c|
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
+ }
642
+ commit opts do |c|
485
643
  c.upsert table, rows
486
644
  end
487
645
  end
@@ -513,7 +671,30 @@ module Google
513
671
  # See [Data
514
672
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
515
673
  #
516
- # @return [Time] The timestamp at which the operation committed.
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
+ #
682
+ # @param [Hash] call_options A hash of values to specify the custom
683
+ # call options, e.g., timeout, retries, etc. Call options are
684
+ # optional. The following settings can be provided:
685
+ #
686
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
687
+ # that overrides the default setting.
688
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
689
+ # setting of retry policy with the following keys:
690
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
691
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
692
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
693
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
694
+ # trigger a retry.
695
+ #
696
+ # @return [Time, CommitResponse] The timestamp at which the operation
697
+ # committed. If commit options are set it returns {CommitResponse}.
517
698
  #
518
699
  # @example
519
700
  # require "google/cloud/spanner"
@@ -525,8 +706,29 @@ module Google
525
706
  # db.insert "users", [{ id: 1, name: "Charlie", active: false },
526
707
  # { id: 2, name: "Harvey", active: true }]
527
708
  #
528
- def insert table, *rows, transaction_id: nil
529
- commit transaction_id: transaction_id do |c|
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
+ }
731
+ commit opts do |c|
530
732
  c.insert table, rows
531
733
  end
532
734
  end
@@ -557,7 +759,30 @@ module Google
557
759
  # See [Data
558
760
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
559
761
  #
560
- # @return [Time] The timestamp at which the operation committed.
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
+ #
770
+ # @param [Hash] call_options A hash of values to specify the custom
771
+ # call options, e.g., timeout, retries, etc. Call options are
772
+ # optional. The following settings can be provided:
773
+ #
774
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
775
+ # that overrides the default setting.
776
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
777
+ # setting of retry policy with the following keys:
778
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
779
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
780
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
781
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
782
+ # trigger a retry.
783
+ #
784
+ # @return [Time, CommitResponse] The timestamp at which the operation
785
+ # committed. If commit options are set it returns {CommitResponse}.
561
786
  #
562
787
  # @example
563
788
  # require "google/cloud/spanner"
@@ -569,8 +794,29 @@ module Google
569
794
  # db.update "users", [{ id: 1, name: "Charlie", active: false },
570
795
  # { id: 2, name: "Harvey", active: true }]
571
796
  #
572
- def update table, *rows, transaction_id: nil
573
- commit transaction_id: transaction_id do |c|
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
+ }
819
+ commit opts do |c|
574
820
  c.update table, rows
575
821
  end
576
822
  end
@@ -603,7 +849,30 @@ module Google
603
849
  # See [Data
604
850
  # types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
605
851
  #
606
- # @return [Time] The timestamp at which the operation committed.
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
+ #
860
+ # @param [Hash] call_options A hash of values to specify the custom
861
+ # call options, e.g., timeout, retries, etc. Call options are
862
+ # optional. The following settings can be provided:
863
+ #
864
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
865
+ # that overrides the default setting.
866
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
867
+ # setting of retry policy with the following keys:
868
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
869
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
870
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
871
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
872
+ # trigger a retry.
873
+ #
874
+ # @return [Time, CommitResponse] The timestamp at which the operation
875
+ # committed. If commit options are set it returns {CommitResponse}.
607
876
  #
608
877
  # @example
609
878
  # require "google/cloud/spanner"
@@ -615,8 +884,29 @@ module Google
615
884
  # db.replace "users", [{ id: 1, name: "Charlie", active: false },
616
885
  # { id: 2, name: "Harvey", active: true }]
617
886
  #
618
- def replace table, *rows, transaction_id: nil
619
- commit transaction_id: transaction_id do |c|
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
+ }
909
+ commit opts do |c|
620
910
  c.replace table, rows
621
911
  end
622
912
  end
@@ -630,8 +920,30 @@ module Google
630
920
  # @param [Object, Array<Object>] keys A single, or list of keys or key
631
921
  # ranges to match returned data to. Values should have exactly as many
632
922
  # elements as there are columns in the primary key.
633
- #
634
- # @return [Time] The timestamp at which the operation committed.
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
+ #
931
+ # @param [Hash] call_options A hash of values to specify the custom
932
+ # call options, e.g., timeout, retries, etc. Call options are
933
+ # optional. The following settings can be provided:
934
+ #
935
+ # * `:timeout` (Numeric) A numeric value of custom timeout in seconds
936
+ # that overrides the default setting.
937
+ # * `:retry_policy` (Hash) A hash of values that overrides the default
938
+ # setting of retry policy with the following keys:
939
+ # * `:initial_delay` (`Numeric`) - The initial delay in seconds.
940
+ # * `:max_delay` (`Numeric`) - The max delay in seconds.
941
+ # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
942
+ # * `:retry_codes` (`Array<String>`) - The error codes that should
943
+ # trigger a retry.
944
+ #
945
+ # @return [Time, CommitResponse] The timestamp at which the operation
946
+ # committed. If commit options are set it returns {CommitResponse}.
635
947
  #
636
948
  # @example
637
949
  # require "google/cloud/spanner"
@@ -642,8 +954,27 @@ module Google
642
954
  #
643
955
  # db.delete "users", [1, 2, 3]
644
956
  #
645
- def delete table, keys = [], transaction_id: nil
646
- commit transaction_id: transaction_id do |c|
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
+ }
977
+ commit opts do |c|
647
978
  c.delete table, keys
648
979
  end
649
980
  end
@@ -675,8 +1006,8 @@ module Google
675
1006
  rescue Google::Cloud::NotFoundError
676
1007
  labels = @grpc.labels.to_h unless @grpc.labels.to_h.empty?
677
1008
  @grpc = service.create_session \
678
- Admin::Database::V1::DatabaseAdminClient.database_path(
679
- project_id, instance_id, database_id
1009
+ V1::Spanner::Paths.database_path(
1010
+ project: project_id, instance: instance_id, database: database_id
680
1011
  ),
681
1012
  labels: labels
682
1013
  @last_updated_at = Time.now
@@ -693,8 +1024,8 @@ module Google
693
1024
  rescue Google::Cloud::NotFoundError
694
1025
  labels = @grpc.labels.to_h unless @grpc.labels.to_h.empty?
695
1026
  @grpc = service.create_session \
696
- Admin::Database::V1::DatabaseAdminClient.database_path(
697
- project_id, instance_id, database_id
1027
+ V1::Spanner::Paths.database_path(
1028
+ project: project_id, instance: instance_id, database: database_id
698
1029
  ),
699
1030
  labels: labels
700
1031
  false
@@ -718,7 +1049,7 @@ module Google
718
1049
 
719
1050
  ##
720
1051
  # @private Creates a new Session instance from a
721
- # Google::Spanner::V1::Session.
1052
+ # `Google::Cloud::Spanner::V1::Session`.
722
1053
  def self.from_grpc grpc, service, query_options: nil
723
1054
  new grpc, service, query_options: query_options
724
1055
  end