google-cloud-spanner 2.18.1 → 2.19.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: 86e6ca163f96c37fa118d05ecf481289318c707f1de83ffb401c20b40afacb69
4
- data.tar.gz: 12cbaad3945956e2da31862d23d0ef66658539fc30daee432879650d2ab3d028
3
+ metadata.gz: 1d164bf2d49bd3b36c04f13b6cda5074c7365a7f9427058d58fb8248061e002e
4
+ data.tar.gz: 857fa9ee08337c4bfd2136ed76083a00f937f81f5036cfbc6a7c6dfacae32668
5
5
  SHA512:
6
- metadata.gz: b866a7a87beb50165b5b1593a4e92a1e0a4684f7a5e7210647aae4ecbe05fcf9f61b1309b00d37deb94e592bc98e541ea1f1104e411a32f6ed9bc4bbde1ee624
7
- data.tar.gz: d8c40babae83b334f95e15ea242f7b1271ecf510cd19722619e759b2a3082df04400b1fc3e78f572a0708ecca76ee68a71192fab92a425d1c27f3c8d58a58aca
6
+ metadata.gz: 7513e1667f78ff92da68dcd9450c4b944bbc3e6fc2ec23c9a84f3f478946dd26fe7c06b6f3abc14f65f6a29d15ac16b82ec729f016338d178cdf0da38e1ce964
7
+ data.tar.gz: 1295194384d4aa5d7ac058177334b7ab6893914718c6572829f4919b58652c0a8b6eb4a4aa2060b45a2a9060ce5cbec8eb0e5b5f5e4ebadaa7db4223910aa252
data/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Release History
2
2
 
3
+ ### 2.19.0 (2024-01-08)
4
+
5
+ #### Features
6
+
7
+ * Support directed read options ([#75](https://github.com/googleapis/ruby-spanner/issues/75))
8
+ #### Bug Fixes
9
+
10
+ * add empty string validation for emulator host ([#73](https://github.com/googleapis/ruby-spanner/issues/73))
11
+
3
12
  ### 2.18.1 (2023-09-19)
4
13
 
5
14
  #### Bug Fixes
@@ -66,12 +66,13 @@ module Google
66
66
  ##
67
67
  # @private Creates a new Spanner BatchClient instance.
68
68
  def initialize project, instance_id, database_id, session_labels: nil,
69
- query_options: nil
69
+ query_options: nil, directed_read_options: nil
70
70
  @project = project
71
71
  @instance_id = instance_id
72
72
  @database_id = database_id
73
73
  @session_labels = session_labels
74
74
  @query_options = query_options
75
+ @directed_read_options = directed_read_options
75
76
  end
76
77
 
77
78
  # The unique identifier for the project.
@@ -110,6 +111,13 @@ module Google
110
111
  @project.database instance_id, database_id
111
112
  end
112
113
 
114
+ # A hash of values to specify the custom directed read options for executing
115
+ # SQL query.
116
+ # @return [Hash]
117
+ def directed_read_options
118
+ @directed_read_options
119
+ end
120
+
113
121
  ##
114
122
  # Returns a {BatchSnapshot} context in which multiple reads and/or
115
123
  # queries can be performed. All reads/queries will use the same
@@ -190,7 +198,7 @@ module Google
190
198
  snp_session.path, strong: strong,
191
199
  timestamp: (timestamp || read_timestamp),
192
200
  staleness: (staleness || exact_staleness)
193
- BatchSnapshot.from_grpc snp_grpc, snp_session
201
+ BatchSnapshot.from_grpc snp_grpc, snp_session, directed_read_options: @directed_read_options
194
202
  end
195
203
 
196
204
  ##
@@ -65,11 +65,15 @@ module Google
65
65
  # @private The Session object.
66
66
  attr_reader :session
67
67
 
68
+ # @private Directed Read Options
69
+ attr_reader :directed_read_options
70
+
68
71
  ##
69
72
  # @private Creates a BatchSnapshot object.
70
- def initialize grpc, session
73
+ def initialize grpc, session, directed_read_options: nil
71
74
  @grpc = grpc
72
75
  @session = session
76
+ @directed_read_options = directed_read_options
73
77
  end
74
78
 
75
79
  ##
@@ -191,6 +195,20 @@ module Google
191
195
  # @param [Boolean] data_boost_enabled If this field is
192
196
  # set `true`, the request will be executed via offline access.
193
197
  # Defaults to `false`.
198
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
199
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
200
+ # or regions should be used for non-transactional reads or queries.
201
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
202
+ # The following settings can be provided:
203
+ #
204
+ # * `:exclude_replicas` (Hash)
205
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
206
+ # Spanner will not route requests to the replicas in this list.
207
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
208
+ # If auto_failover_disabled is set to true and
209
+ # all replicas are exhausted without finding a healthy replica,
210
+ # Spanner will wait for a replica in the list to become available,
211
+ # requests may fail due to DEADLINE_EXCEEDED errors.
194
212
  #
195
213
  # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
196
214
  # created by the query partition.
@@ -214,7 +232,8 @@ module Google
214
232
  #
215
233
  def partition_query sql, params: nil, types: nil,
216
234
  partition_size_bytes: nil, max_partitions: nil,
217
- query_options: nil, call_options: nil, data_boost_enabled: false
235
+ query_options: nil, call_options: nil, data_boost_enabled: false,
236
+ directed_read_options: nil
218
237
  ensure_session!
219
238
 
220
239
  params, types = Convert.to_input_params_and_types params, types
@@ -235,7 +254,8 @@ module Google
235
254
  transaction: tx_selector,
236
255
  partition_token: grpc.partition_token,
237
256
  query_options: query_options,
238
- data_boost_enabled: data_boost_enabled
257
+ data_boost_enabled: data_boost_enabled,
258
+ directed_read_options: (directed_read_options || @directed_read_options)
239
259
  }.compact
240
260
  )
241
261
  Partition.from_execute_sql_grpc execute_sql_grpc
@@ -284,6 +304,20 @@ module Google
284
304
  # @param [Boolean] data_boost_enabled If this field is
285
305
  # set `true`, the request will be executed via offline access.
286
306
  # Defaults to `false`.
307
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
308
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
309
+ # or regions should be used for non-transactional reads or queries.
310
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
311
+ # The following settings can be provided:
312
+ #
313
+ # * `:exclude_replicas` (Hash)
314
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
315
+ # Spanner will not route requests to the replicas in this list.
316
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
317
+ # If auto_failover_disabled is set to true and
318
+ # all replicas are exhausted without finding a healthy replica,
319
+ # Spanner will wait for a replica in the list to become available,
320
+ # requests may fail due to DEADLINE_EXCEEDED errors.
287
321
  #
288
322
  # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
289
323
  # created by the read partition.
@@ -305,7 +339,8 @@ module Google
305
339
  #
306
340
  def partition_read table, columns, keys: nil, index: nil,
307
341
  partition_size_bytes: nil, max_partitions: nil,
308
- call_options: nil, data_boost_enabled: false
342
+ call_options: nil, data_boost_enabled: false,
343
+ directed_read_options: nil
309
344
  ensure_session!
310
345
 
311
346
  columns = Array(columns).map(&:to_s)
@@ -329,7 +364,8 @@ module Google
329
364
  index: index,
330
365
  transaction: tx_selector,
331
366
  partition_token: grpc.partition_token,
332
- data_boost_enabled: data_boost_enabled
367
+ data_boost_enabled: data_boost_enabled,
368
+ directed_read_options: (directed_read_options || @directed_read_options)
333
369
  }.compact
334
370
  )
335
371
  Partition.from_read_grpc read_grpc
@@ -498,6 +534,20 @@ module Google
498
534
  # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
499
535
  # * `:retry_codes` (`Array<String>`) - The error codes that should
500
536
  # trigger a retry.
537
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
538
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
539
+ # or regions should be used for non-transactional reads or queries.
540
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
541
+ # The following settings can be provided:
542
+ #
543
+ # * `:exclude_replicas` (Hash)
544
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
545
+ # Spanner will not route requests to the replicas in this list.
546
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
547
+ # If auto_failover_disabled is set to true and
548
+ # all replicas are exhausted without finding a healthy replica,
549
+ # Spanner will wait for a replica in the list to become available,
550
+ # requests may fail due to DEADLINE_EXCEEDED errors.
501
551
  #
502
552
  # @return [Google::Cloud::Spanner::Results] The results of the query
503
553
  # execution.
@@ -645,7 +695,7 @@ module Google
645
695
  # end
646
696
  #
647
697
  def execute_query sql, params: nil, types: nil, query_options: nil,
648
- call_options: nil
698
+ call_options: nil, directed_read_options: nil
649
699
  ensure_session!
650
700
 
651
701
  params, types = Convert.to_input_params_and_types params, types
@@ -653,7 +703,8 @@ module Google
653
703
  session.execute_query sql, params: params, types: types,
654
704
  transaction: tx_selector,
655
705
  query_options: query_options,
656
- call_options: call_options
706
+ call_options: call_options,
707
+ directed_read_options: (directed_read_options || @directed_read_options)
657
708
  end
658
709
  alias execute execute_query
659
710
  alias query execute_query
@@ -688,6 +739,20 @@ module Google
688
739
  # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
689
740
  # * `:retry_codes` (`Array<String>`) - The error codes that should
690
741
  # trigger a retry.
742
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
743
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
744
+ # or regions should be used for non-transactional reads or queries.
745
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
746
+ # The following settings can be provided:
747
+ #
748
+ # * `:exclude_replicas` (Hash)
749
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
750
+ # Spanner will not route requests to the replicas in this list.
751
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
752
+ # If auto_failover_disabled is set to true and
753
+ # all replicas are exhausted without finding a healthy replica,
754
+ # Spanner will wait for a replica in the list to become available,
755
+ # requests may fail due to DEADLINE_EXCEEDED errors.
691
756
  #
692
757
  # @return [Google::Cloud::Spanner::Results] The results of the read
693
758
  # operation.
@@ -706,7 +771,7 @@ module Google
706
771
  # end
707
772
  #
708
773
  def read table, columns, keys: nil, index: nil, limit: nil,
709
- call_options: nil
774
+ call_options: nil, directed_read_options: nil
710
775
  ensure_session!
711
776
 
712
777
  columns = Array(columns).map(&:to_s)
@@ -714,7 +779,8 @@ module Google
714
779
 
715
780
  session.read table, columns, keys: keys, index: index, limit: limit,
716
781
  transaction: tx_selector,
717
- call_options: call_options
782
+ call_options: call_options,
783
+ directed_read_options: (directed_read_options || @directed_read_options)
718
784
  end
719
785
 
720
786
  ##
@@ -784,8 +850,8 @@ module Google
784
850
  ##
785
851
  # @private Creates a new BatchSnapshot instance from a
786
852
  # `Google::Cloud::Spanner::V1::Transaction`.
787
- def self.from_grpc grpc, session
788
- new grpc, session
853
+ def self.from_grpc grpc, session, directed_read_options: nil
854
+ new grpc, session, directed_read_options: directed_read_options
789
855
  end
790
856
 
791
857
  protected
@@ -813,7 +879,8 @@ module Google
813
879
  partition_token: partition.execute.partition_token,
814
880
  query_options: query_options,
815
881
  call_options: call_options,
816
- data_boost_enabled: partition.execute.data_boost_enabled
882
+ data_boost_enabled: partition.execute.data_boost_enabled,
883
+ directed_read_options: partition.execute.directed_read_options
817
884
  end
818
885
 
819
886
  def execute_partition_read partition, call_options: nil
@@ -824,7 +891,8 @@ module Google
824
891
  transaction: partition.read.transaction,
825
892
  partition_token: partition.read.partition_token,
826
893
  call_options: call_options,
827
- data_boost_enabled: partition.read.data_boost_enabled
894
+ data_boost_enabled: partition.read.data_boost_enabled,
895
+ directed_read_options: partition.read.directed_read_options
828
896
  end
829
897
  end
830
898
  end
@@ -56,12 +56,14 @@ module Google
56
56
  ##
57
57
  # @private Creates a new Spanner Client instance.
58
58
  def initialize project, instance_id, database_id, session_labels: nil,
59
- pool_opts: {}, query_options: nil, database_role: nil
59
+ pool_opts: {}, query_options: nil, database_role: nil,
60
+ directed_read_options: nil
60
61
  @project = project
61
62
  @instance_id = instance_id
62
63
  @database_id = database_id
63
64
  @database_role = database_role
64
65
  @session_labels = session_labels
66
+ @directed_read_options = directed_read_options
65
67
  @pool = Pool.new self, **pool_opts
66
68
  @query_options = query_options
67
69
  end
@@ -115,6 +117,13 @@ module Google
115
117
  @query_options
116
118
  end
117
119
 
120
+ # A hash of values to specify the custom directed read options for executing
121
+ # SQL query.
122
+ # @return [Hash]
123
+ def directed_read_options
124
+ @directed_read_options
125
+ end
126
+
118
127
  ##
119
128
  # Executes a SQL query.
120
129
  #
@@ -264,6 +273,20 @@ module Google
264
273
  # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
265
274
  # * `:retry_codes` (`Array<String>`) - The error codes that should
266
275
  # trigger a retry.
276
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
277
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
278
+ # or regions should be used for non-transactional reads or queries.
279
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
280
+ # The following settings can be provided:
281
+ #
282
+ # * `:exclude_replicas` (Hash)
283
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
284
+ # Spanner will not route requests to the replicas in this list.
285
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
286
+ # If auto_failover_disabled is set to true and
287
+ # all replicas are exhausted without finding a healthy replica,
288
+ # Spanner will wait for a replica in the list to become available,
289
+ # requests may fail due to DEADLINE_EXCEEDED errors.
267
290
  #
268
291
  # @return [Google::Cloud::Spanner::Results] The results of the query
269
292
  # execution.
@@ -435,7 +458,7 @@ module Google
435
458
  #
436
459
  def execute_query sql, params: nil, types: nil, single_use: nil,
437
460
  query_options: nil, request_options: nil,
438
- call_options: nil
461
+ call_options: nil, directed_read_options: nil
439
462
  validate_single_use_args! single_use
440
463
  ensure_service!
441
464
 
@@ -448,7 +471,7 @@ module Google
448
471
  results = session.execute_query \
449
472
  sql, params: params, types: types, transaction: single_use_tx,
450
473
  query_options: query_options, request_options: request_options,
451
- call_options: call_options
474
+ call_options: call_options, directed_read_options: (directed_read_options || @directed_read_options)
452
475
  end
453
476
  results
454
477
  end
@@ -828,6 +851,20 @@ module Google
828
851
  # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
829
852
  # * `:retry_codes` (`Array<String>`) - The error codes that should
830
853
  # trigger a retry.
854
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
855
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
856
+ # or regions should be used for non-transactional reads or queries.
857
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
858
+ # The following settings can be provided:
859
+ #
860
+ # * `:exclude_replicas` (Hash)
861
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
862
+ # Spanner will not route requests to the replicas in this list.
863
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
864
+ # If auto_failover_disabled is set to true
865
+ # and all replicas are exhausted without finding a healthy replica,
866
+ # Spanner will wait for a replica in the list to become available,
867
+ # requests may fail due to DEADLINE_EXCEEDED errors.
831
868
  #
832
869
  # @return [Google::Cloud::Spanner::Results] The results of the read.
833
870
  #
@@ -911,7 +948,8 @@ module Google
911
948
  # end
912
949
  #
913
950
  def read table, columns, keys: nil, index: nil, limit: nil,
914
- single_use: nil, request_options: nil, call_options: nil
951
+ single_use: nil, request_options: nil, call_options: nil,
952
+ directed_read_options: nil
915
953
  validate_single_use_args! single_use
916
954
  ensure_service!
917
955
 
@@ -927,7 +965,8 @@ module Google
927
965
  table, columns, keys: keys, index: index, limit: limit,
928
966
  transaction: single_use_tx,
929
967
  request_options: request_options,
930
- call_options: call_options
968
+ call_options: call_options,
969
+ directed_read_options: (directed_read_options || @directed_read_options)
931
970
  end
932
971
  results
933
972
  end
@@ -1935,7 +1974,7 @@ module Google
1935
1974
  staleness: (staleness || exact_staleness),
1936
1975
  call_options: call_options
1937
1976
  Thread.current[IS_TRANSACTION_RUNNING_KEY] = true
1938
- snp = Snapshot.from_grpc snp_grpc, session
1977
+ snp = Snapshot.from_grpc snp_grpc, session, @directed_read_options
1939
1978
  yield snp if block_given?
1940
1979
  ensure
1941
1980
  Thread.current[IS_TRANSACTION_RUNNING_KEY] = nil
@@ -2159,7 +2198,9 @@ module Google
2159
2198
  session_count,
2160
2199
  labels: @session_labels,
2161
2200
  database_role: @database_role
2162
- resp.session.map { |grpc| Session.from_grpc grpc, @project.service, query_options: @query_options }
2201
+ resp.session.map do |grpc|
2202
+ Session.from_grpc grpc, @project.service, query_options: @query_options
2203
+ end
2163
2204
  end
2164
2205
 
2165
2206
  # @private
@@ -547,6 +547,20 @@ module Google
547
547
  # available optimizer version.
548
548
  # * `:optimizer_statistics_package` (String) Statistics package to
549
549
  # use. Empty to use the database default.
550
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
551
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
552
+ # or regions should be used for non-transactional reads or queries.
553
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
554
+ # The following settings can be provided:
555
+ #
556
+ # * `:exclude_replicas` (Hash)
557
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
558
+ # Spanner will not route requests to the replicas in this list.
559
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
560
+ # If auto_failover_disabled is set to true
561
+ # and all replicas are exhausted without finding a healthy replica,
562
+ # Spanner will wait for a replica in the list to become available,
563
+ # requests may fail due to DEADLINE_EXCEEDED errors.
550
564
  #
551
565
  # @return [Client] The newly created client.
552
566
  #
@@ -566,7 +580,7 @@ module Google
566
580
  # end
567
581
  #
568
582
  def client instance_id, database_id, pool: {}, labels: nil,
569
- query_options: nil, database_role: nil
583
+ query_options: nil, database_role: nil, directed_read_options: nil
570
584
  # Convert from possible Google::Protobuf::Map
571
585
  labels = labels.to_h { |k, v| [String(k), String(v)] } if labels
572
586
  # Configs set by environment variables take over client-level configs.
@@ -579,7 +593,8 @@ module Google
579
593
  session_labels: labels,
580
594
  pool_opts: valid_session_pool_options(pool),
581
595
  query_options: query_options,
582
- database_role: database_role
596
+ database_role: database_role,
597
+ directed_read_options: directed_read_options
583
598
  end
584
599
 
585
600
  ##
@@ -614,6 +629,20 @@ module Google
614
629
  # available optimizer version.
615
630
  # * `:optimizer_statistics_package` (String) Statistics package to
616
631
  # use. Empty to use the database default.
632
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
633
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
634
+ # or regions should be used for non-transactional reads or queries.
635
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
636
+ # The following settings can be provided:
637
+ #
638
+ # * `:exclude_replicas` (Hash)
639
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
640
+ # Spanner will not route requests to the replicas in this list.
641
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
642
+ # If auto_failover_disabled is set to true
643
+ # and all replicas are exhausted without finding a healthy replica,
644
+ # Spanner will wait for a replica in the list to become available,
645
+ # requests may fail due to DEADLINE_EXCEEDED errors.
617
646
  #
618
647
  # @return [Client] The newly created client.
619
648
  #
@@ -643,11 +672,11 @@ module Google
643
672
  # new_partition
644
673
  #
645
674
  def batch_client instance_id, database_id, labels: nil,
646
- query_options: nil
675
+ query_options: nil, directed_read_options: nil
647
676
  # Convert from possible Google::Protobuf::Map
648
677
  labels = labels.to_h { |k, v| [String(k), String(v)] } if labels
649
678
  BatchClient.new self, instance_id, database_id, session_labels: labels,
650
- query_options: query_options
679
+ query_options: query_options, directed_read_options: directed_read_options
651
680
  end
652
681
 
653
682
  protected
@@ -329,7 +329,8 @@ module Google
329
329
  params: nil, types: nil, resume_token: nil,
330
330
  partition_token: nil, seqno: nil,
331
331
  query_options: nil, request_options: nil,
332
- call_options: nil, data_boost_enabled: nil
332
+ call_options: nil, data_boost_enabled: nil,
333
+ directed_read_options: nil
333
334
  opts = default_options session_name: session_name,
334
335
  call_options: call_options
335
336
  request = {
@@ -342,7 +343,8 @@ module Google
342
343
  partition_token: partition_token,
343
344
  seqno: seqno,
344
345
  query_options: query_options,
345
- request_options: request_options
346
+ request_options: request_options,
347
+ directed_read_options: directed_read_options
346
348
  }
347
349
  request[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
348
350
  service.execute_streaming_sql request, opts
@@ -367,7 +369,7 @@ module Google
367
369
  index: nil, transaction: nil, limit: nil,
368
370
  resume_token: nil, partition_token: nil,
369
371
  request_options: nil, call_options: nil,
370
- data_boost_enabled: nil
372
+ data_boost_enabled: nil, directed_read_options: nil
371
373
  opts = default_options session_name: session_name,
372
374
  call_options: call_options
373
375
  request = {
@@ -377,6 +379,7 @@ module Google
377
379
  partition_token: partition_token, request_options: request_options
378
380
  }
379
381
  request[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
382
+ request[:directed_read_options] = directed_read_options unless directed_read_options.nil?
380
383
  service.streaming_read request, opts
381
384
  end
382
385
 
@@ -338,13 +338,10 @@ module Google
338
338
  #
339
339
  def execute_query sql, params: nil, types: nil, transaction: nil,
340
340
  partition_token: nil, seqno: nil, query_options: nil,
341
- request_options: nil, call_options: nil, data_boost_enabled: nil
341
+ request_options: nil, call_options: nil, data_boost_enabled: nil,
342
+ directed_read_options: nil
342
343
  ensure_service!
343
- if query_options.nil?
344
- query_options = @query_options
345
- else
346
- query_options = @query_options.merge query_options unless @query_options.nil?
347
- end
344
+ query_options = merge_if_present query_options, @query_options
348
345
 
349
346
  execute_query_options = {
350
347
  transaction: transaction, params: params, types: types,
@@ -353,6 +350,7 @@ module Google
353
350
  call_options: call_options
354
351
  }
355
352
  execute_query_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
353
+ execute_query_options[:directed_read_options] = directed_read_options unless directed_read_options.nil?
356
354
 
357
355
  response = service.execute_streaming_sql path, sql, **execute_query_options
358
356
 
@@ -499,7 +497,7 @@ module Google
499
497
  #
500
498
  def read table, columns, keys: nil, index: nil, limit: nil,
501
499
  transaction: nil, partition_token: nil, request_options: nil,
502
- call_options: nil, data_boost_enabled: nil
500
+ call_options: nil, data_boost_enabled: nil, directed_read_options: nil
503
501
  ensure_service!
504
502
 
505
503
  read_options = {
@@ -507,10 +505,10 @@ module Google
507
505
  transaction: transaction,
508
506
  partition_token: partition_token,
509
507
  request_options: request_options,
510
- call_options: call_options,
511
- data_boost_enabled: data_boost_enabled
508
+ call_options: call_options
512
509
  }
513
510
  read_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
511
+ read_options[:directed_read_options] = directed_read_options unless directed_read_options.nil?
514
512
 
515
513
  response = service.streaming_read_table \
516
514
  path, table, columns, **read_options
@@ -1265,6 +1263,14 @@ module Google
1265
1263
  def ensure_service!
1266
1264
  raise "Must have active connection to service" unless service
1267
1265
  end
1266
+
1267
+ def merge_if_present hash, hash_to_merge
1268
+ if hash.nil?
1269
+ hash_to_merge
1270
+ else
1271
+ hash_to_merge.nil? ? hash : hash_to_merge.merge(hash)
1272
+ end
1273
+ end
1268
1274
  end
1269
1275
  end
1270
1276
  end
@@ -142,6 +142,20 @@ module Google
142
142
  # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
143
143
  # * `:retry_codes` (`Array<String>`) - The error codes that should
144
144
  # trigger a retry.
145
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
146
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
147
+ # or regions should be used for non-transactional reads or queries.
148
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
149
+ # The following settings can be provided:
150
+ #
151
+ # * `:exclude_replicas` (Hash)
152
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
153
+ # Spanner will not route requests to the replicas in this list.
154
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
155
+ # If auto_failover_disabled is set to true
156
+ # and all replicas are exhausted without finding a healthy replica,
157
+ # Spanner will wait for a replica in the list to become available,
158
+ # requests may fail due to DEADLINE_EXCEEDED errors.
145
159
  #
146
160
  # @return [Google::Cloud::Spanner::Results] The results of the query
147
161
  # execution.
@@ -288,14 +302,15 @@ module Google
288
302
  # end
289
303
  #
290
304
  def execute_query sql, params: nil, types: nil, query_options: nil,
291
- call_options: nil
305
+ call_options: nil, directed_read_options: nil
292
306
  ensure_session!
293
307
 
294
308
  params, types = Convert.to_input_params_and_types params, types
295
309
  session.execute_query sql, params: params, types: types,
296
310
  transaction: tx_selector,
297
311
  query_options: query_options,
298
- call_options: call_options
312
+ call_options: call_options,
313
+ directed_read_options: (directed_read_options || @directed_read_options)
299
314
  end
300
315
  alias execute execute_query
301
316
  alias query execute_query
@@ -330,6 +345,20 @@ module Google
330
345
  # * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
331
346
  # * `:retry_codes` (`Array<String>`) - The error codes that should
332
347
  # trigger a retry.
348
+ # @param [Hash] directed_read_options Client options used to set the directed_read_options
349
+ # for all ReadRequests and ExecuteSqlRequests that indicates which replicas
350
+ # or regions should be used for non-transactional reads or queries.
351
+ # Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
352
+ # The following settings can be provided:
353
+ #
354
+ # * `:exclude_replicas` (Hash)
355
+ # Exclude_replicas indicates what replicas should be excluded from serving requests.
356
+ # Spanner will not route requests to the replicas in this list.
357
+ # * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
358
+ # If auto_failover_disabled is set to true
359
+ # and all replicas are exhausted without finding a healthy replica,
360
+ # Spanner will wait for a replica in the list to become available,
361
+ # requests may fail due to DEADLINE_EXCEEDED errors.
333
362
  #
334
363
  # @return [Google::Cloud::Spanner::Results] The results of the read
335
364
  # operation.
@@ -349,7 +378,7 @@ module Google
349
378
  # end
350
379
  #
351
380
  def read table, columns, keys: nil, index: nil, limit: nil,
352
- call_options: nil
381
+ call_options: nil, directed_read_options: nil
353
382
  ensure_session!
354
383
 
355
384
  columns = Array(columns).map(&:to_s)
@@ -357,7 +386,8 @@ module Google
357
386
 
358
387
  session.read table, columns, keys: keys, index: index, limit: limit,
359
388
  transaction: tx_selector,
360
- call_options: call_options
389
+ call_options: call_options,
390
+ directed_read_options: (directed_read_options || @directed_read_options)
361
391
  end
362
392
 
363
393
  ##
@@ -477,10 +507,11 @@ module Google
477
507
  ##
478
508
  # @private Creates a new Snapshot instance from a
479
509
  # `Google::Cloud::Spanner::V1::Transaction`.
480
- def self.from_grpc grpc, session
510
+ def self.from_grpc grpc, session, directed_read_options
481
511
  new.tap do |s|
482
512
  s.instance_variable_set :@grpc, grpc
483
513
  s.instance_variable_set :@session, session
514
+ s.instance_variable_set :@directed_read_options, directed_read_options
484
515
  end
485
516
  end
486
517
 
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module Spanner
19
- VERSION = "2.18.1".freeze
19
+ VERSION = "2.19.0".freeze
20
20
  end
21
21
  end
22
22
  end
@@ -96,7 +96,7 @@ module Google
96
96
  project_id ||= project || default_project_id
97
97
  scope ||= configure.scope
98
98
  timeout ||= configure.timeout
99
- emulator_host ||= configure.emulator_host
99
+ emulator_host = present_or_nil(emulator_host) || present_or_nil(configure.emulator_host)
100
100
  endpoint ||= emulator_host || configure.endpoint
101
101
  credentials ||= keyfile
102
102
  lib_name ||= configure.lib_name
@@ -181,6 +181,13 @@ module Google
181
181
  Google::Cloud.configure.credentials ||
182
182
  Spanner::Credentials.default(scope: scope)
183
183
  end
184
+
185
+ ##
186
+ # @private checks if string is not nil or empty string
187
+ # returns the string if present else nil
188
+ def self.present_or_nil str
189
+ str.to_s.strip.empty? ? nil : str
190
+ end
184
191
  end
185
192
  end
186
193
 
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.18.1
4
+ version: 2.19.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: 2023-09-19 00:00:00.000000000 Z
12
+ date: 2024-01-08 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: google-cloud-core
@@ -348,7 +348,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
348
348
  - !ruby/object:Gem::Version
349
349
  version: '0'
350
350
  requirements: []
351
- rubygems_version: 3.4.19
351
+ rubygems_version: 3.5.3
352
352
  signing_key:
353
353
  specification_version: 4
354
354
  summary: API Client library for Google Cloud Spanner API