google-cloud-spanner 2.18.1 → 2.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86e6ca163f96c37fa118d05ecf481289318c707f1de83ffb401c20b40afacb69
-  data.tar.gz: 12cbaad3945956e2da31862d23d0ef66658539fc30daee432879650d2ab3d028
+  metadata.gz: 1d164bf2d49bd3b36c04f13b6cda5074c7365a7f9427058d58fb8248061e002e
+  data.tar.gz: 857fa9ee08337c4bfd2136ed76083a00f937f81f5036cfbc6a7c6dfacae32668
 SHA512:
-  metadata.gz: b866a7a87beb50165b5b1593a4e92a1e0a4684f7a5e7210647aae4ecbe05fcf9f61b1309b00d37deb94e592bc98e541ea1f1104e411a32f6ed9bc4bbde1ee624
-  data.tar.gz: d8c40babae83b334f95e15ea242f7b1271ecf510cd19722619e759b2a3082df04400b1fc3e78f572a0708ecca76ee68a71192fab92a425d1c27f3c8d58a58aca
+  metadata.gz: 7513e1667f78ff92da68dcd9450c4b944bbc3e6fc2ec23c9a84f3f478946dd26fe7c06b6f3abc14f65f6a29d15ac16b82ec729f016338d178cdf0da38e1ce964
+  data.tar.gz: 1295194384d4aa5d7ac058177334b7ab6893914718c6572829f4919b58652c0a8b6eb4a4aa2060b45a2a9060ce5cbec8eb0e5b5f5e4ebadaa7db4223910aa252

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 2.19.0 (2024-01-08)
+
+#### Features
+
+* Support directed read options ([#75](https://github.com/googleapis/ruby-spanner/issues/75)) 
+#### Bug Fixes
+
+* add empty string validation for emulator host ([#73](https://github.com/googleapis/ruby-spanner/issues/73)) 
+
 ### 2.18.1 (2023-09-19)
 
 #### Bug Fixes

data/lib/google/cloud/spanner/batch_client.rb

@@ -66,12 +66,13 @@ module Google
         ##
         # @private Creates a new Spanner BatchClient instance.
         def initialize project, instance_id, database_id, session_labels: nil,
-                       query_options: nil
+                       query_options: nil, directed_read_options: nil
           @project = project
           @instance_id = instance_id
           @database_id = database_id
           @session_labels = session_labels
           @query_options = query_options
+          @directed_read_options = directed_read_options
         end
 
         # The unique identifier for the project.
@@ -110,6 +111,13 @@ module Google
           @project.database instance_id, database_id
         end
 
+        # A hash of values to specify the custom directed read options for executing
+        # SQL query.
+        # @return [Hash]
+        def directed_read_options
+          @directed_read_options
+        end
+
         ##
         # Returns a {BatchSnapshot} context in which multiple reads and/or
         # queries can be performed. All reads/queries will use the same
@@ -190,7 +198,7 @@ module Google
             snp_session.path, strong: strong,
                               timestamp: (timestamp || read_timestamp),
                               staleness: (staleness || exact_staleness)
-          BatchSnapshot.from_grpc snp_grpc, snp_session
+          BatchSnapshot.from_grpc snp_grpc, snp_session, directed_read_options: @directed_read_options
         end
 
         ##

data/lib/google/cloud/spanner/batch_snapshot.rb

@@ -65,11 +65,15 @@ module Google
         # @private The Session object.
         attr_reader :session
 
+        # @private Directed Read Options
+        attr_reader :directed_read_options
+
         ##
         # @private Creates a BatchSnapshot object.
-        def initialize grpc, session
+        def initialize grpc, session, directed_read_options: nil
           @grpc = grpc
           @session = session
+          @directed_read_options = directed_read_options
         end
 
         ##
@@ -191,6 +195,20 @@ module Google
         # @param [Boolean] data_boost_enabled  If this field is
         #   set `true`, the request will be executed via offline access.
         #   Defaults to `false`.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true and
+        #      all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the query partition.
@@ -214,7 +232,8 @@ module Google
         #
         def partition_query sql, params: nil, types: nil,
                             partition_size_bytes: nil, max_partitions: nil,
-                            query_options: nil, call_options: nil, data_boost_enabled: false
+                            query_options: nil, call_options: nil, data_boost_enabled: false,
+                            directed_read_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
@@ -235,7 +254,8 @@ module Google
                 transaction: tx_selector,
                 partition_token: grpc.partition_token,
                 query_options: query_options,
-                data_boost_enabled: data_boost_enabled
+                data_boost_enabled: data_boost_enabled,
+                directed_read_options: (directed_read_options || @directed_read_options)
               }.compact
             )
             Partition.from_execute_sql_grpc execute_sql_grpc
@@ -284,6 +304,20 @@ module Google
         # @param [Boolean] data_boost_enabled  If this field is
         #   set `true`, the request will be executed via offline access.
         #   Defaults to `false`.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true and
+        #      all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the read partition.
@@ -305,7 +339,8 @@ module Google
         #
         def partition_read table, columns, keys: nil, index: nil,
                            partition_size_bytes: nil, max_partitions: nil,
-                           call_options: nil, data_boost_enabled: false
+                           call_options: nil, data_boost_enabled: false,
+                           directed_read_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -329,7 +364,8 @@ module Google
                 index: index,
                 transaction: tx_selector,
                 partition_token: grpc.partition_token,
-                data_boost_enabled: data_boost_enabled
+                data_boost_enabled: data_boost_enabled,
+                directed_read_options: (directed_read_options || @directed_read_options)
               }.compact
             )
             Partition.from_read_grpc read_grpc
@@ -498,6 +534,20 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true and
+        #      all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -645,7 +695,7 @@ module Google
         #   end
         #
         def execute_query sql, params: nil, types: nil, query_options: nil,
-                          call_options: nil
+                          call_options: nil, directed_read_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
@@ -653,7 +703,8 @@ module Google
           session.execute_query sql, params: params, types: types,
                                 transaction: tx_selector,
                                 query_options: query_options,
-                                call_options: call_options
+                                call_options: call_options,
+                                directed_read_options: (directed_read_options || @directed_read_options)
         end
         alias execute execute_query
         alias query execute_query
@@ -688,6 +739,20 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true and
+        #      all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read
         #   operation.
@@ -706,7 +771,7 @@ module Google
         #   end
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
-                 call_options: nil
+                 call_options: nil, directed_read_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -714,7 +779,8 @@ module Google
 
           session.read table, columns, keys: keys, index: index, limit: limit,
                                        transaction: tx_selector,
-                                       call_options: call_options
+                                       call_options: call_options,
+                                       directed_read_options: (directed_read_options || @directed_read_options)
         end
 
         ##
@@ -784,8 +850,8 @@ module Google
         ##
         # @private Creates a new BatchSnapshot instance from a
         # `Google::Cloud::Spanner::V1::Transaction`.
-        def self.from_grpc grpc, session
-          new grpc, session
+        def self.from_grpc grpc, session, directed_read_options: nil
+          new grpc, session, directed_read_options: directed_read_options
         end
 
         protected
@@ -813,7 +879,8 @@ module Google
             partition_token: partition.execute.partition_token,
             query_options: query_options,
             call_options: call_options,
-            data_boost_enabled: partition.execute.data_boost_enabled
+            data_boost_enabled: partition.execute.data_boost_enabled,
+            directed_read_options: partition.execute.directed_read_options
         end
 
         def execute_partition_read partition, call_options: nil
@@ -824,7 +891,8 @@ module Google
                        transaction: partition.read.transaction,
                        partition_token: partition.read.partition_token,
                        call_options: call_options,
-                       data_boost_enabled: partition.read.data_boost_enabled
+                       data_boost_enabled: partition.read.data_boost_enabled,
+                       directed_read_options: partition.read.directed_read_options
         end
       end
     end

data/lib/google/cloud/spanner/client.rb

@@ -56,12 +56,14 @@ module Google
         ##
         # @private Creates a new Spanner Client instance.
         def initialize project, instance_id, database_id, session_labels: nil,
-                       pool_opts: {}, query_options: nil, database_role: nil
+                       pool_opts: {}, query_options: nil, database_role: nil,
+                       directed_read_options: nil
           @project = project
           @instance_id = instance_id
           @database_id = database_id
           @database_role = database_role
           @session_labels = session_labels
+          @directed_read_options = directed_read_options
           @pool = Pool.new self, **pool_opts
           @query_options = query_options
         end
@@ -115,6 +117,13 @@ module Google
           @query_options
         end
 
+        # A hash of values to specify the custom directed read options for executing
+        # SQL query.
+        # @return [Hash]
+        def directed_read_options
+          @directed_read_options
+        end
+
         ##
         # Executes a SQL query.
         #
@@ -264,6 +273,20 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true and
+        #      all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -435,7 +458,7 @@ module Google
         #
         def execute_query sql, params: nil, types: nil, single_use: nil,
                           query_options: nil, request_options: nil,
-                          call_options: nil
+                          call_options: nil, directed_read_options: nil
           validate_single_use_args! single_use
           ensure_service!
 
@@ -448,7 +471,7 @@ module Google
             results = session.execute_query \
               sql, params: params, types: types, transaction: single_use_tx,
               query_options: query_options, request_options: request_options,
-              call_options: call_options
+              call_options: call_options, directed_read_options: (directed_read_options || @directed_read_options)
           end
           results
         end
@@ -828,6 +851,20 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true
+        #      and all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read.
         #
@@ -911,7 +948,8 @@ module Google
         #   end
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
-                 single_use: nil, request_options: nil, call_options: nil
+                 single_use: nil, request_options: nil, call_options: nil,
+                 directed_read_options: nil
           validate_single_use_args! single_use
           ensure_service!
 
@@ -927,7 +965,8 @@ module Google
               table, columns, keys: keys, index: index, limit: limit,
                               transaction: single_use_tx,
                               request_options: request_options,
-                              call_options: call_options
+                              call_options: call_options,
+                              directed_read_options: (directed_read_options || @directed_read_options)
           end
           results
         end
@@ -1935,7 +1974,7 @@ module Google
                             staleness: (staleness || exact_staleness),
                             call_options: call_options
             Thread.current[IS_TRANSACTION_RUNNING_KEY] = true
-            snp = Snapshot.from_grpc snp_grpc, session
+            snp = Snapshot.from_grpc snp_grpc, session, @directed_read_options
             yield snp if block_given?
           ensure
             Thread.current[IS_TRANSACTION_RUNNING_KEY] = nil
@@ -2159,7 +2198,9 @@ module Google
             session_count,
             labels: @session_labels,
             database_role: @database_role
-          resp.session.map { |grpc| Session.from_grpc grpc, @project.service, query_options: @query_options }
+          resp.session.map do |grpc|
+            Session.from_grpc grpc, @project.service, query_options: @query_options
+          end
         end
 
         # @private

data/lib/google/cloud/spanner/project.rb

@@ -547,6 +547,20 @@ module Google
         #     available optimizer version.
         #   * `:optimizer_statistics_package` (String) Statistics package to
         #     use. Empty to use the database default.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true
+        #      and all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Client] The newly created client.
         #
@@ -566,7 +580,7 @@ module Google
         #   end
         #
         def client instance_id, database_id, pool: {}, labels: nil,
-                   query_options: nil, database_role: nil
+                   query_options: nil, database_role: nil, directed_read_options: nil
           # Convert from possible Google::Protobuf::Map
           labels = labels.to_h { |k, v| [String(k), String(v)] } if labels
           # Configs set by environment variables take over client-level configs.
@@ -579,7 +593,8 @@ module Google
                      session_labels: labels,
                      pool_opts: valid_session_pool_options(pool),
                      query_options: query_options,
-                     database_role: database_role
+                     database_role: database_role,
+                     directed_read_options: directed_read_options
         end
 
         ##
@@ -614,6 +629,20 @@ module Google
         #     available optimizer version.
         #   * `:optimizer_statistics_package` (String) Statistics package to
         #     use. Empty to use the database default.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true
+        #      and all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Client] The newly created client.
         #
@@ -643,11 +672,11 @@ module Google
         #     new_partition
         #
         def batch_client instance_id, database_id, labels: nil,
-                         query_options: nil
+                         query_options: nil, directed_read_options: nil
           # Convert from possible Google::Protobuf::Map
           labels = labels.to_h { |k, v| [String(k), String(v)] } if labels
           BatchClient.new self, instance_id, database_id, session_labels: labels,
-                          query_options: query_options
+                          query_options: query_options, directed_read_options: directed_read_options
         end
 
         protected

data/lib/google/cloud/spanner/service.rb

@@ -329,7 +329,8 @@ module Google
                                   params: nil, types: nil, resume_token: nil,
                                   partition_token: nil, seqno: nil,
                                   query_options: nil, request_options: nil,
-                                  call_options: nil, data_boost_enabled: nil
+                                  call_options: nil, data_boost_enabled: nil,
+                                  directed_read_options: nil
           opts = default_options session_name: session_name,
                                  call_options: call_options
           request =  {
@@ -342,7 +343,8 @@ module Google
             partition_token: partition_token,
             seqno: seqno,
             query_options: query_options,
-            request_options: request_options
+            request_options: request_options,
+            directed_read_options: directed_read_options
           }
           request[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
           service.execute_streaming_sql request, opts
@@ -367,7 +369,7 @@ module Google
                                  index: nil, transaction: nil, limit: nil,
                                  resume_token: nil, partition_token: nil,
                                  request_options: nil, call_options: nil,
-                                 data_boost_enabled: nil
+                                 data_boost_enabled: nil, directed_read_options: nil
           opts = default_options session_name: session_name,
                                  call_options: call_options
           request = {
@@ -377,6 +379,7 @@ module Google
             partition_token: partition_token, request_options: request_options
           }
           request[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
+          request[:directed_read_options] = directed_read_options unless directed_read_options.nil?
           service.streaming_read request, opts
         end
 

data/lib/google/cloud/spanner/session.rb

@@ -338,13 +338,10 @@ module Google
         #
         def execute_query sql, params: nil, types: nil, transaction: nil,
                           partition_token: nil, seqno: nil, query_options: nil,
-                          request_options: nil, call_options: nil, data_boost_enabled: nil
+                          request_options: nil, call_options: nil, data_boost_enabled: nil,
+                          directed_read_options: nil
           ensure_service!
-          if query_options.nil?
-            query_options = @query_options
-          else
-            query_options = @query_options.merge query_options unless @query_options.nil?
-          end
+          query_options = merge_if_present query_options, @query_options
 
           execute_query_options = {
             transaction: transaction, params: params, types: types,
@@ -353,6 +350,7 @@ module Google
             call_options: call_options
           }
           execute_query_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
+          execute_query_options[:directed_read_options] = directed_read_options unless directed_read_options.nil?
 
           response = service.execute_streaming_sql path, sql, **execute_query_options
 
@@ -499,7 +497,7 @@ module Google
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
                  transaction: nil, partition_token: nil, request_options: nil,
-                 call_options: nil, data_boost_enabled: nil
+                 call_options: nil, data_boost_enabled: nil, directed_read_options: nil
           ensure_service!
 
           read_options = {
@@ -507,10 +505,10 @@ module Google
             transaction: transaction,
             partition_token: partition_token,
             request_options: request_options,
-            call_options: call_options,
-            data_boost_enabled: data_boost_enabled
+            call_options: call_options
           }
           read_options[:data_boost_enabled] = data_boost_enabled unless data_boost_enabled.nil?
+          read_options[:directed_read_options] = directed_read_options unless directed_read_options.nil?
 
           response = service.streaming_read_table \
             path, table, columns, **read_options
@@ -1265,6 +1263,14 @@ module Google
         def ensure_service!
           raise "Must have active connection to service" unless service
         end
+
+        def merge_if_present hash, hash_to_merge
+          if hash.nil?
+            hash_to_merge
+          else
+            hash_to_merge.nil? ? hash : hash_to_merge.merge(hash)
+          end
+        end
       end
     end
   end

data/lib/google/cloud/spanner/snapshot.rb

@@ -142,6 +142,20 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true
+        #      and all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -288,14 +302,15 @@ module Google
         #   end
         #
         def execute_query sql, params: nil, types: nil, query_options: nil,
-                          call_options: nil
+                          call_options: nil, directed_read_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
           session.execute_query sql, params: params, types: types,
                                      transaction: tx_selector,
                                      query_options: query_options,
-                                     call_options: call_options
+                                     call_options: call_options,
+                                     directed_read_options: (directed_read_options || @directed_read_options)
         end
         alias execute execute_query
         alias query execute_query
@@ -330,6 +345,20 @@ module Google
         #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
+        # @param [Hash]  directed_read_options Client options used to set the directed_read_options
+        #    for all ReadRequests and ExecuteSqlRequests that indicates which replicas
+        #    or regions should be used for non-transactional reads or queries.
+        #    Will represent [`Google::Cloud::Spanner::V1::DirectedReadOptions`](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-DirectedReadOptions)
+        #   The following settings can be provided:
+        #
+        #   * `:exclude_replicas` (Hash)
+        #      Exclude_replicas indicates what replicas should be excluded from serving requests.
+        #      Spanner will not route requests to the replicas in this list.
+        #   * `:include_replicas` (Hash) Include_replicas indicates the order of replicas to process the request.
+        #      If auto_failover_disabled is set to true
+        #      and all replicas are exhausted without finding a healthy replica,
+        #      Spanner will wait for a replica in the list to become available,
+        #      requests may fail due to DEADLINE_EXCEEDED errors.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read
         #   operation.
@@ -349,7 +378,7 @@ module Google
         #   end
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
-                 call_options: nil
+                 call_options: nil, directed_read_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -357,7 +386,8 @@ module Google
 
           session.read table, columns, keys: keys, index: index, limit: limit,
                                        transaction: tx_selector,
-                                       call_options: call_options
+                                       call_options: call_options,
+                                       directed_read_options: (directed_read_options || @directed_read_options)
         end
 
         ##
@@ -477,10 +507,11 @@ module Google
         ##
         # @private Creates a new Snapshot instance from a
         # `Google::Cloud::Spanner::V1::Transaction`.
-        def self.from_grpc grpc, session
+        def self.from_grpc grpc, session, directed_read_options
           new.tap do |s|
             s.instance_variable_set :@grpc,    grpc
             s.instance_variable_set :@session, session
+            s.instance_variable_set :@directed_read_options, directed_read_options
           end
         end
 

data/lib/google/cloud/spanner/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.18.1".freeze
+      VERSION = "2.19.0".freeze
     end
   end
 end

data/lib/google/cloud/spanner.rb

@@ -96,7 +96,7 @@ module Google
         project_id    ||= project || default_project_id
         scope         ||= configure.scope
         timeout       ||= configure.timeout
-        emulator_host ||= configure.emulator_host
+        emulator_host = present_or_nil(emulator_host) || present_or_nil(configure.emulator_host)
         endpoint      ||= emulator_host || configure.endpoint
         credentials   ||= keyfile
         lib_name      ||= configure.lib_name
@@ -181,6 +181,13 @@ module Google
           Google::Cloud.configure.credentials ||
           Spanner::Credentials.default(scope: scope)
       end
+
+      ##
+      # @private checks if string is not nil or empty string
+      # returns the string if present else nil
+      def self.present_or_nil str
+        str.to_s.strip.empty? ? nil : str
+      end
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.18.1
+  version: 2.19.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-19 00:00:00.000000000 Z
+date: 2024-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -348,7 +348,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.3
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Spanner API