google-cloud-spanner 2.19.1 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cf89ec86ecf1bed2fcbec728dca49cb5b7b18c6b27b187289b80bc70cceab87
-  data.tar.gz: 862f6429db6150c4254005fca8e0697fcda4139a1ce837c0ed88eee82e3c24f2
+  metadata.gz: bb4b25a92a8c1064831ca356c5504c6114fde3efbda272ff4553dda86bf1a902
+  data.tar.gz: 66c330a8e53e6e9ffac6735008586c5ad0027629e71f66f8401e2c58ea4394a9
 SHA512:
-  metadata.gz: 8d6a031a4a1af4aa914725f26fd3ff7921ab718f73df8774fd9aef5d7c419cd0d2733f5987e8d3afe54a3cb25e7bf31bf98579239fcdda4aa582ae872acea441
-  data.tar.gz: 247ad7856b80831eb5039b8eec87a409a8c88f825dd0c65eebae40ebf9c17814870a14bcbf6316211d53cc6d1b4232b8834629c74960d4ac21b6568cd00240a5
+  metadata.gz: 6f296b9eb6930cad1c242402bc2dc8cb0ac47eaef1761acb598f35aaa63779d33192c0d92d5df852fe711ff7ad54c7b0f7695d2a0055b55a7dd05b80aa3d855d
+  data.tar.gz: e3de3a8796cbcade1973cd2b4d3d5a632c6677173f24cd1ba0b9dfa7d8355e93122d9d0c0c3926d442271d057517adf9125cfb61e2f896faa54ec324d590aed4

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 2.20.0 (2024-01-31)
+
+#### Features
+
+* Support Leader Aware Routing ([#78](https://github.com/googleapis/ruby-spanner/issues/78)) 
+
 ### 2.19.1 (2024-01-24)
 
 #### Bug Fixes

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

@@ -24,6 +24,7 @@ require "google/cloud/spanner/range"
 require "google/cloud/spanner/column_value"
 require "google/cloud/spanner/convert"
 require "google/cloud/spanner/commit_response"
+require "google/cloud/spanner/lar_headers"
 
 module Google
   module Cloud
@@ -466,12 +467,14 @@ module Google
           request_options = Convert.to_request_options request_options,
                                                        tag_type: :request_tag
           single_use_tx = single_use_transaction single_use
+          route_to_leader = LARHeaders.execute_query true
           results = nil
           @pool.with_session do |session|
             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, directed_read_options: (directed_read_options || @directed_read_options)
+              call_options: call_options, directed_read_options: (directed_read_options || @directed_read_options),
+              route_to_leader: route_to_leader
           end
           results
         end
@@ -735,14 +738,14 @@ module Google
           params, types = Convert.to_input_params_and_types params, types
           request_options = Convert.to_request_options request_options,
                                                        tag_type: :request_tag
-
+          route_to_leader = LARHeaders.partition_query
           results = nil
           @pool.with_session do |session|
             results = session.execute_query \
               sql, params: params, types: types,
               transaction: pdml_transaction(session),
               query_options: query_options, request_options: request_options,
-              call_options: call_options
+              call_options: call_options, route_to_leader: route_to_leader
           end
           # Stream all PartialResultSet to get ResultSetStats
           results.rows.to_a
@@ -956,6 +959,7 @@ module Google
           columns = Array(columns).map(&:to_s)
           keys = Convert.to_key_set keys
           single_use_tx = single_use_transaction single_use
+          route_to_leader = LARHeaders.read false
           request_options = Convert.to_request_options request_options,
                                                        tag_type: :request_tag
 
@@ -966,7 +970,8 @@ module Google
                               transaction: single_use_tx,
                               request_options: request_options,
                               call_options: call_options,
-                              directed_read_options: (directed_read_options || @directed_read_options)
+                              directed_read_options: (directed_read_options || @directed_read_options),
+                              route_to_leader: route_to_leader
           end
           results
         end

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

@@ -0,0 +1,100 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # @private Helper module to access header values
+      # for Leader Aware Routing (LAR).
+      #
+      # For a multi-region Cloud Spanner instance, the majority of
+      # the write latency is attributed to the network round trip
+      # caused by several RPCs between SpanFE and SpanServer. This
+      # latency is amplified when the client application is deployed
+      # away from the leader region.
+      #
+      # To decrease the latency, we use LAR to help Google Front End (GFE)
+      # or Cloudpath Front End (CFE) to route requests directly to the
+      # leader region or the nearest non-leader region.
+      #
+      # For every RPC, we pass the header `x-goog-spanner-route-to-leader`,
+      # whose value is either 'true' or 'false'. Some RPCs (such as admin APIs)
+      # don't pass the header since they're deprecated in the handwritten
+      # client. Also, users of the client can choose to opt out of the
+      # LAR feature, in which case, we don't pass the header.
+      #
+      # This module lists the header values for different RPCs to be used
+      # by the client. These values are expected to be constant. Some RPCs
+      # (such as `execute_streaming_sql`) can have different values
+      # depending on whether they're run within read-only transactions
+      # or read-write transactions.
+      #
+      module LARHeaders
+        class << self
+          def begin_transaction is_read_write_tx
+            is_read_write_tx ? "true" : "false"
+          end
+
+          def read is_read_write_tx
+            is_read_write_tx ? "true" : "false"
+          end
+
+          def execute_query is_read_write_tx
+            is_read_write_tx ? "true" : "false"
+          end
+
+          def commit
+            "true"
+          end
+
+          def execute_batch_dml
+            "true"
+          end
+
+          def create_session
+            "true"
+          end
+
+          def batch_create_sessions
+            "true"
+          end
+
+          def delete_session
+            "false"
+          end
+
+          # rubocop:disable Naming/AccessorMethodName
+          def get_session
+            "true"
+          end
+          # rubocop:enable Naming/AccessorMethodName
+
+          def partition_read
+            "true"
+          end
+
+          def partition_query
+            "true"
+          end
+
+          def rollback
+            "true"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -20,6 +20,7 @@ require "google/cloud/spanner/v1"
 require "google/cloud/spanner/admin/instance/v1"
 require "google/cloud/spanner/admin/database/v1"
 require "google/cloud/spanner/convert"
+require "google/cloud/spanner/lar_headers"
 
 module Google
   module Cloud
@@ -35,6 +36,7 @@ module Google
         attr_accessor :lib_name
         attr_accessor :lib_version
         attr_accessor :quota_project
+        attr_accessor :enable_leader_aware_routing
 
         RST_STREAM_INTERNAL_ERROR = "Received RST_STREAM".freeze
         EOS_INTERNAL_ERROR = "Received unexpected EOS on DATA frame from server".freeze
@@ -42,7 +44,8 @@ module Google
         ##
         # Creates a new Service instance.
         def initialize project, credentials, quota_project: nil,
-                       host: nil, timeout: nil, lib_name: nil, lib_version: nil
+                       host: nil, timeout: nil, lib_name: nil, lib_version: nil,
+                       enable_leader_aware_routing: nil
           @project = project
           @credentials = credentials
           @quota_project = quota_project || (credentials.quota_project_id if credentials.respond_to? :quota_project_id)
@@ -50,6 +53,7 @@ module Google
           @timeout = timeout
           @lib_name = lib_name
           @lib_version = lib_version
+          @enable_leader_aware_routing = enable_leader_aware_routing
         end
 
         def channel
@@ -290,15 +294,19 @@ module Google
         end
 
         def get_session session_name, call_options: nil
+          route_to_leader = LARHeaders.get_session
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           service.get_session({ name: session_name }, opts)
         end
 
         def create_session database_name, labels: nil,
                            call_options: nil, database_role: nil
+          route_to_leader = LARHeaders.create_session
           opts = default_options session_name: database_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           session = V1::Session.new labels: labels, creator_role: database_role if labels || database_role
           service.create_session(
             { database: database_name, session: session }, opts
@@ -307,8 +315,10 @@ module Google
 
         def batch_create_sessions database_name, session_count, labels: nil,
                                   call_options: nil, database_role: nil
+          route_to_leader = LARHeaders.batch_create_sessions
           opts = default_options session_name: database_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           session = V1::Session.new labels: labels, creator_role: database_role if labels || database_role
           # The response may have fewer sessions than requested in the RPC.
           request = {
@@ -320,8 +330,10 @@ module Google
         end
 
         def delete_session session_name, call_options: nil
+          route_to_leader = LARHeaders.delete_session
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           service.delete_session({ name: session_name }, opts)
         end
 
@@ -330,9 +342,11 @@ module Google
                                   partition_token: nil, seqno: nil,
                                   query_options: nil, request_options: nil,
                                   call_options: nil, data_boost_enabled: nil,
-                                  directed_read_options: nil
+                                  directed_read_options: nil,
+                                  route_to_leader: nil
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request =  {
             session: session_name,
             sql: sql,
@@ -352,8 +366,10 @@ module Google
 
         def execute_batch_dml session_name, transaction, statements, seqno,
                               request_options: nil, call_options: nil
+          route_to_leader = LARHeaders.execute_batch_dml
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           statements = statements.map(&:to_grpc)
           request = {
             session: session_name,
@@ -369,9 +385,11 @@ module Google
                                  index: nil, transaction: nil, limit: nil,
                                  resume_token: nil, partition_token: nil,
                                  request_options: nil, call_options: nil,
-                                 data_boost_enabled: nil, directed_read_options: nil
+                                 data_boost_enabled: nil, directed_read_options: nil,
+                                 route_to_leader: nil
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request = {
             session: session_name, table: table_name, columns: columns,
             key_set: keys, transaction: transaction, index: index,
@@ -388,9 +406,10 @@ module Google
                            max_partitions: nil, call_options: nil
           partition_opts = partition_options partition_size_bytes,
                                              max_partitions
-
+          route_to_leader = LARHeaders.partition_read
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request = {
             session: session_name, table: table_name, key_set: keys,
             transaction: transaction, index: index, columns: columns,
@@ -404,9 +423,10 @@ module Google
                             max_partitions: nil, call_options: nil
           partition_opts = partition_options partition_size_bytes,
                                              max_partitions
-
+          route_to_leader = LARHeaders.partition_query
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request = {
             session: session_name, sql: sql, transaction: transaction,
             params: params, param_types: types,
@@ -417,6 +437,7 @@ module Google
 
         def commit session_name, mutations = [], transaction_id: nil,
                    commit_options: nil, request_options: nil, call_options: nil
+          route_to_leader = LARHeaders.commit
           tx_opts = nil
           if transaction_id.nil?
             tx_opts = V1::TransactionOptions.new(
@@ -424,7 +445,8 @@ module Google
             )
           end
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request = {
             session: session_name, transaction_id: transaction_id,
             single_use_transaction: tx_opts, mutations: mutations,
@@ -439,19 +461,23 @@ module Google
         end
 
         def rollback session_name, transaction_id, call_options: nil
+          route_to_leader = LARHeaders.rollback
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request = { session: session_name, transaction_id: transaction_id }
           service.rollback request, opts
         end
 
         def begin_transaction session_name, request_options: nil,
-                              call_options: nil
+                              call_options: nil,
+                              route_to_leader: nil
           tx_opts = V1::TransactionOptions.new(
             read_write: V1::TransactionOptions::ReadWrite.new
           )
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request = {
             session: session_name,
             options: tx_opts,
@@ -482,8 +508,10 @@ module Google
           tx_opts = V1::TransactionOptions.new(
             partitioned_dml: V1::TransactionOptions::PartitionedDml.new
           )
+          route_to_leader = LARHeaders.begin_transaction true
           opts = default_options session_name: session_name,
-                                 call_options: call_options
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
           request = { session: session_name, options: tx_opts }
           service.begin_transaction request, opts
         end
@@ -608,12 +636,17 @@ module Google
           value << " gccl"
         end
 
-        def default_options session_name: nil, call_options: nil
+        def default_options session_name: nil, call_options: nil, route_to_leader: nil
           opts = {}
+          metadata = {}
           if session_name
             default_prefix = session_name.split("/sessions/").first
-            opts[:metadata] = { "google-cloud-resource-prefix" => default_prefix }
+            metadata["google-cloud-resource-prefix"] = default_prefix
+          end
+          if @enable_leader_aware_routing && !route_to_leader.nil?
+            metadata["x-goog-spanner-route-to-leader"] = route_to_leader
           end
+          opts[:metadata] = metadata
           if call_options
             opts[:timeout] = call_options[:timeout] if call_options[:timeout]
             opts[:retry_policy] = call_options[:retry_policy] if call_options[:retry_policy]

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

@@ -339,7 +339,7 @@ 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,
-                          directed_read_options: nil
+                          directed_read_options: nil, route_to_leader: nil
           ensure_service!
           query_options = merge_if_present query_options, @query_options
 
@@ -347,7 +347,8 @@ module Google
             transaction: transaction, params: params, types: types,
             partition_token: partition_token, seqno: seqno,
             query_options: query_options, request_options: request_options,
-            call_options: call_options
+            call_options: call_options,
+            route_to_leader: route_to_leader
           }
           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?
@@ -497,7 +498,8 @@ 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, directed_read_options: nil
+                 call_options: nil, data_boost_enabled: nil, directed_read_options: nil,
+                 route_to_leader: nil
           ensure_service!
 
           read_options = {
@@ -505,7 +507,8 @@ module Google
             transaction: transaction,
             partition_token: partition_token,
             request_options: request_options,
-            call_options: call_options
+            call_options: call_options,
+            route_to_leader: route_to_leader
           }
           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?
@@ -1178,7 +1181,8 @@ module Google
         # @private
         # Creates a new transaction object every time.
         def create_transaction
-          tx_grpc = service.begin_transaction path
+          route_to_leader = LARHeaders.begin_transaction true
+          tx_grpc = service.begin_transaction path, route_to_leader: route_to_leader
           Transaction.from_grpc tx_grpc, self
         end
 
@@ -1214,7 +1218,8 @@ module Google
         # Keeps the session alive by executing `"SELECT 1"`.
         def keepalive!
           ensure_service!
-          execute_query "SELECT 1"
+          route_to_leader = LARHeaders.execute_query false
+          execute_query "SELECT 1", route_to_leader: route_to_leader
           true
         rescue Google::Cloud::NotFoundError
           labels = @grpc.labels.to_h unless @grpc.labels.to_h.empty?

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

@@ -18,6 +18,7 @@ require "google/cloud/spanner/convert"
 require "google/cloud/spanner/results"
 require "google/cloud/spanner/commit"
 require "google/cloud/spanner/batch_update_results"
+require "google/cloud/spanner/lar_headers"
 
 module Google
   module Cloud
@@ -361,13 +362,15 @@ module Google
 
           params, types = Convert.to_input_params_and_types params, types
           request_options = build_request_options request_options
+          route_to_leader = LARHeaders.execute_query true
 
           safe_execute do |seqno|
             results = session.execute_query sql, params: params, types: types,
                                             transaction: tx_selector, seqno: seqno,
                                             query_options: query_options,
                                             request_options: request_options,
-                                            call_options: call_options
+                                            call_options: call_options,
+                                            route_to_leader: route_to_leader
             @grpc ||= results.transaction
             results
           end
@@ -715,12 +718,14 @@ module Google
           columns = Array(columns).map(&:to_s)
           keys = Convert.to_key_set keys
           request_options = build_request_options request_options
+          route_to_leader = LARHeaders.read true
 
           safe_execute do
             results = session.read table, columns, keys: keys, index: index, limit: limit,
                                    transaction: tx_selector,
                                    request_options: request_options,
-                                   call_options: call_options
+                                   call_options: call_options,
+                                   route_to_leader: route_to_leader
             @grpc ||= results.transaction
             results
           end
@@ -1190,7 +1195,8 @@ module Google
           @mutex.synchronize do
             return if existing_transaction?
             ensure_session!
-            @grpc = service.begin_transaction session.path
+            route_to_leader = LARHeaders.begin_transaction true
+            @grpc = service.begin_transaction session.path, route_to_leader: route_to_leader
           end
         end
 

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

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

data/lib/google/cloud/spanner.rb

@@ -82,6 +82,8 @@ module Google
       #   `spanner-activerecord/0.0.1` is provided custom library name and
       #   version and `gccl/1.13.1` represents the Cloud Spanner Ruby library
       #   with version.
+      # @param enable_leader_aware_routing [Boolean] Specifies whether Leader
+      #   Aware Routing should be enabled. Defaults to true.
       #
       # @return [Google::Cloud::Spanner::Project]
       #
@@ -92,7 +94,8 @@ module Google
       #
       def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
                    endpoint: nil, project: nil, keyfile: nil,
-                   emulator_host: nil, lib_name: nil, lib_version: nil
+                   emulator_host: nil, lib_name: nil, lib_version: nil,
+                   enable_leader_aware_routing: true
         project_id    ||= project || default_project_id
         scope         ||= configure.scope
         timeout       ||= configure.timeout
@@ -122,7 +125,8 @@ module Google
           Spanner::Service.new(
             project_id, credentials, quota_project: configure.quota_project,
             host: endpoint, timeout: timeout, lib_name: lib_name,
-            lib_version: lib_version
+            lib_version: lib_version,
+            enable_leader_aware_routing: enable_leader_aware_routing
           ),
           query_options: configure.query_options
         )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.19.1
+  version: 2.20.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-24 00:00:00.000000000 Z
+date: 2024-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -317,6 +317,7 @@ files:
 - lib/google/cloud/spanner/instance/config/list.rb
 - lib/google/cloud/spanner/instance/job.rb
 - lib/google/cloud/spanner/instance/list.rb
+- lib/google/cloud/spanner/lar_headers.rb
 - lib/google/cloud/spanner/partition.rb
 - lib/google/cloud/spanner/policy.rb
 - lib/google/cloud/spanner/pool.rb