google-cloud-spanner 2.29.0 → 2.31.0

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

@@ -16,6 +16,7 @@
 require "concurrent"
 require "google/cloud/spanner/errors"
 require "google/cloud/spanner/session"
+require "google/cloud/spanner/session_creation_options"
 
 module Google
   module Cloud
@@ -37,7 +38,9 @@ module Google
         attr_accessor :sessions_in_use
 
         # Creates a new Session pool that manages non-multiplexed sessions.
-        # @param client [::Google::Cloud::Spanner::Client] A `Spanner::Client` reference
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @param session_creation_options [::Google::Cloud::Spanner::SessionCreationOptions] Required.
+        #   Options used for session creation. E.g. session labels.
         # @param min [::Integer] Min number of sessions to keep
         # @param max [::Integer] Max number of sessions to keep
         # @param keepalive [::Numeric] How long after their last usage the sessions can be reclaimed
@@ -46,9 +49,10 @@ module Google
         # @param threads [::Integer, nil] Number of threads in the thread pool that is used for keepalive and
         #   release session actions. If `nil` the Pool will choose a reasonable default.
         # @private
-        def initialize client, min: 10, max: 100, keepalive: 1800,
+        def initialize service, session_creation_options, min: 10, max: 100, keepalive: 1800,
                        fail: true, threads: nil
-          @client = client
+          @service = service
+          @session_creation_options = session_creation_options
           @min = min
           @max = max
           @keepalive = keepalive
@@ -127,7 +131,7 @@ module Google
           nil
         end
 
-        def reset
+        def reset!
           close
           init
 
@@ -137,6 +141,7 @@ module Google
 
           true
         end
+        alias reset reset!
 
         def close
           shutdown
@@ -181,7 +186,7 @@ module Google
           # init the keepalive task
           create_keepalive_task!
           # init session stack
-          @sessions_available = @client.batch_create_new_sessions @min
+          @sessions_available = batch_create_new_sessions @min
           @sessions_in_use = {}
         end
 
@@ -209,7 +214,7 @@ module Google
           end
 
           begin
-            session = @client.create_new_session
+            session = create_new_session
           rescue StandardError => e
             @mutex.synchronize do
               @new_sessions_in_process -= 1
@@ -239,6 +244,60 @@ module Google
         def future(&)
           Concurrent::Future.new(executor: @thread_pool, &).execute
         end
+
+        # Creates a new `Spanner::Session`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
+        def create_new_session
+          ensure_service!
+          grpc = @service.create_session(
+            @session_creation_options.database_path,
+            labels:  @session_creation_options.session_labels,
+            database_role: @session_creation_options.session_creator_role
+          )
+
+          Session.from_grpc grpc, @service, query_options: @query_options
+        end
+
+        # Creates a batch of new session objects of size `total`.
+        # Makes multiple RPCs if necessary. Returns empty array if total is 0.
+        # @private
+        # @return [::Array<::Google::Cloud::Spanner::Session>]
+        def batch_create_new_sessions total
+          sessions = []
+          remaining = total
+          while remaining.positive?
+            sessions += batch_create_sessions remaining
+            remaining = total - sessions.count
+          end
+          sessions
+        end
+
+        # Tries to creates a batch of new session objects of size `session_count`.
+        # The response may have fewer sessions than requested in the RPC.
+        # @private
+        # @return [::Array<::Google::Cloud::Spanner::Session>]
+        def batch_create_sessions session_count
+          ensure_service!
+          resp = @service.batch_create_sessions(
+            @session_creation_options.database_path,
+            session_count,
+            labels:  @session_creation_options.session_labels,
+            database_role: @session_creation_options.session_creator_role
+          )
+
+          resp.session.map do |grpc|
+            Session.from_grpc grpc, @service, query_options: @query_options
+          end
+        end
+
+        # Raise an error unless an active connection to the service is available.
+        # @private
+        # @raise [::StandardError]
+        # @return [void]
+        def ensure_service!
+          raise "Must have active connection to service" unless @service
+        end
       end
     end
   end

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

@@ -509,25 +509,9 @@ module Google
         #   Required.
         # @param [String] database_id The unique identifier for the database.
         #   Required.
-        # @param [Hash] pool Settings to control how and when sessions are
-        #   managed by the client. The following settings can be provided:
-        #
-        #   * `:min` (Integer) Minimum number of sessions that the client will
-        #     maintain at any point in time. The default is 10.
-        #   * `:max` (Integer) Maximum number of sessions that the client will
-        #     have at any point in time. The default is 100.
-        #   * `:keepalive` (Numeric) The amount of time a session can be idle
-        #     before an attempt is made to prevent the idle sessions from being
-        #     closed by the Cloud Spanner service. The default is 1800 (30
-        #     minutes).
-        #   * `:fail` (true/false) When `true` the client raises a
-        #     {SessionLimitError} when the client has allocated the `max` number
-        #     of sessions. When `false` the client blocks until a session
-        #     becomes available. The default is `true`.
-        #   * `:threads` (Integer) The number of threads in the thread pool. The
-        #     default is twice the number of available CPUs.
-        #   * `:write_ratio` (Float) Deprecated. This field is no longer needed
-        #     and will be removed in a future release.
+        # @param [Hash] pool Optional. Defaults to `{}`. Deprecated.
+        #   @deprecated This parameter is non-functional since the multiplexed SessionCache does not require
+        #   pool options.
         # @param [Hash] labels The labels to be applied to all sessions
         #   created by the client. Cloud Labels are a flexible and lightweight
         #   mechanism for organizing cloud resources into groups that reflect a
@@ -567,7 +551,7 @@ module Google
         #      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.
+        # @return [::Google::Cloud::Spanner::Client] The newly created client.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -594,9 +578,11 @@ module Google
           else
             query_options = query_options.merge @query_options unless @query_options.nil?
           end
+
+          _pool = pool # unused. Here only to avoid having to disable Rubocop's Lint/UnusedMethodArgument
+
           Client.new self, instance_id, database_id,
                      session_labels: labels,
-                     pool_opts: valid_session_pool_options(pool),
                      query_options: query_options,
                      database_role: database_role,
                      directed_read_options: directed_read_options
@@ -649,7 +635,7 @@ module Google
         #      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.
+        # @return [::Google::Cloud::Spanner::BatchClient] The newly created client.
         #
         # @example
         #   require "google/cloud/spanner"

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

@@ -45,32 +45,42 @@ module Google
       #   end
       #
       class Results
-        # The `V1::ResultSetMetadata` protobuf object from the first
-        # PartialResultSet.
-        # @private
-        # @return [::Google::Cloud::Spanner::V1::ResultSetMetadata]
-        attr_reader :metadata
-
         # Creates a new Results instance.
         # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` reference.
         # @param partial_result_sets [::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>]
         #   Raw enumerable from grpc `StreamingRead` call.
         # @param session_name [::String] Required.
-        #   The session in which the transaction to be committed is running.
+        #   The name of the session for the operation that created these Results.
         #   Values are of the form:
         #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
         # @param metadata [::Google::Cloud::Spanner::V1::ResultSetMetadata] ParialResultSet metadata object
         # @param stats [::Google::Cloud::Spanner::V1::ResultSetStats] Query plan and execution statistics
         #   for the statement that produced this streaming result set.
+        # @param precommit_token_notify [::Proc, nil] Optional.
+        #   The notification function for the precommit token.
         # @private
-        def initialize service, partial_result_sets, session_name, metadata, stats
+        def initialize service, partial_result_sets, session_name, metadata, stats, precommit_token_notify: nil
           @service = service
           @partial_result_sets = partial_result_sets
           @session_name = session_name
           @metadata = metadata
           @stats = stats
+
+          # The notification function for the precommit token.
+          # `Results` object will see precommit tokens while iterating if it were created
+          # in the context of an RW transaction on a multiplexed session.
+          # Precommit token is a passthrough parameter that that transaction will need to supply in order to Commit.
+          # There can be multiple precommit tokens in the stream
+          # (should be at least 2 -- with the first and last PartialResultSet).
+          @precommit_token_notify = precommit_token_notify
         end
 
+        # The `V1::ResultSetMetadata` protobuf object from the first
+        # PartialResultSet.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::ResultSetMetadata]
+        attr_reader :metadata
+
         ##
         # The read timestamp chosen for single-use snapshots (read-only
         # transactions).
@@ -162,13 +172,21 @@ module Google
                 should_retry_request = false
               end
 
-              # @type [::Google::Cloud::Spanner::V1::PartialResultsSet]
+              # @type [::Google::Cloud::Spanner::V1::PartialResultSet]
               grpc = @partial_result_sets.next
 
               # metadata should be set before the first iteration...
               @metadata ||= grpc.metadata
               @stats ||= grpc.stats
 
+              # The precommit token should be issued on first and last stream element.
+              # These two precommit tokens can be different.
+              # If these Results are created in the context of a `Spanner::Transaction`,
+              # that `Transaction` object is the one keeping track of the precommit token and should be notified.
+              if grpc.precommit_token && @precommit_token_notify
+                @precommit_token_notify.call(grpc.precommit_token)
+              end
+
               buffered_responses << grpc
 
               if (grpc.resume_token && grpc.resume_token != "") ||
@@ -327,17 +345,26 @@ module Google
         #   Raw enumerable from underlying grpc call.
         # @param service [::Google::Cloud::Spanner::Service] The `Spanner::Service` reference.
         # @param session_name [::String] Required.
-        #   The session in which the transaction to be committed is running.
+        #   The name of the session for the operation that created these Results.
         #   Values are of the form:
         #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        # @param precommit_token_notify [::Proc, nil] Optional.
+        #   The notification function for the precommit token.
         # @private
         # @return [::Google::Cloud::Spanner::Results]
-        def self.from_partial_result_sets partial_result_sets, service, session_name
+        def self.from_partial_result_sets partial_result_sets, service, session_name, precommit_token_notify: nil
           # @type [::Google::Cloud::Spanner::V1::PartialResultSet]
           partial_result_set = partial_result_sets.peek
           metadata = partial_result_set.metadata
           stats = partial_result_set.stats
-          new service, partial_result_sets, session_name, metadata, stats
+          results = new service, partial_result_sets, session_name, metadata, stats,
+                        precommit_token_notify: precommit_token_notify
+
+          if partial_result_set.precommit_token && precommit_token_notify
+            precommit_token_notify.call partial_result_set.precommit_token
+          end
+
+          results
         rescue GRPC::BadStatus => e
           raise Google::Cloud::Error.from_error(e)
         end
@@ -355,10 +382,14 @@ module Google
         #   that were sent to the `service.execute_streaming_sql`. This hash joins params needed to
         #   construct `::Gapic::CallOptions`, e.g. `call_options` and header-related `route_to_leader`
         #   with params specific to `execute_streaming_sql`, such as `seqno`.
+        # @param precommit_token_notify [::Proc, nil] Optional.
+        #   The notification function for the precommit token.
         # @private
         # @return [::Google::Cloud::Spanner::Results]
-        def self.from_execute_query_response response, service, session_name, sql, execute_query_options
-          from_partial_result_sets(response, service, session_name).tap do |results|
+        def self.from_execute_query_response response, service, session_name, sql, execute_query_options,
+                                             precommit_token_notify: nil
+          from_partial_result_sets(response, service, session_name,
+                                   precommit_token_notify: precommit_token_notify).tap do |results|
             execute_query_options_copy = execute_query_options.dup
             unless results.metadata.transaction.nil?
               execute_query_options_copy[:transaction] = V1::TransactionSelector.new id: results.metadata.transaction.id
@@ -384,10 +415,14 @@ module Google
         #   that were sent to the `service.streaming_read_table`. This hash joins params needed to
         #   construct `::Gapic::CallOptions`, e.g. `call_options` and header-related `route_to_leader`
         #   with params specific to `streaming_read_table`, such as `keys`.
+        # @param precommit_token_notify [::Proc, nil] Optional.
+        #   The notification function for the precommit token.
         # @private
         # @return [::Google::Cloud::Spanner::Results]
-        def self.from_read_response response, service, session_name, table, columns, read_options
-          from_partial_result_sets(response, service, session_name).tap do |results|
+        def self.from_read_response response, service, session_name, table, columns, read_options,
+                                    precommit_token_notify: nil
+          from_partial_result_sets(response, service, session_name,
+                                   precommit_token_notify: precommit_token_notify).tap do |results|
             read_options_copy = read_options.dup
             unless results.metadata.transaction.nil?
               read_options_copy[:transaction] = V1::TransactionSelector.new id: results.metadata.transaction.id

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

@@ -352,17 +352,17 @@ module Google
         # @param database_name [::String] The full name of the database.
         # @param labels [::Hash, nil] Optional. The labels to be applied to all sessions
         #   created by the client. Example: `"team" => "billing-service"`.
-        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
-        #   call options. Example option `:timeout`.
         # @param database_role [::String, nil] Optional. The Spanner session creator role.
         #   Example: `analyst`.
         # @param multiplexed [::Boolean] Optional. Default to `false`.
         #   If `true`, specifies a multiplexed session.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
         # @return [::Google::Cloud::Spanner::V1::Session]
         # @private
         def create_session database_name, labels: nil,
-                           call_options: nil, database_role: nil,
-                           multiplexed: false
+                           database_role: nil, multiplexed: false,
+                           call_options: nil
           route_to_leader = LARHeaders.create_session
           opts = default_options(
             session_name: database_name,
@@ -524,23 +524,30 @@ module Google
         # @param exclude_txn_from_change_streams [::Boolean] Optional. Defaults to `false`.
         #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
         #   or write transactions from being tracked in change streams.
+        # @param isolation_level [::Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] Optional.
+        #   The isolation level for the transaction.
         # @param commit_options [::Hash, nil]  Optional. A hash of commit options.
         #   Example option: `:return_commit_stats`.
         # @param request_options [::Hash, nil] Optional. Common request options.
         #   Example option: `:priority`.
         # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
         #   call options. Example option `:timeout`.
+        # @param precommit_token [::Google::Cloud::Spanner::V1::MultiplexedSessionPrecommitToken, nil] Optional.
+        #    If the read-write transaction was executed on a multiplexed session, then a precommit token
+        #    with the highest sequence number received in this transaction attempt must be included.
         # @private
         # @return [::Google::Cloud::Spanner::V1::CommitResponse]
         def commit session_name, mutations = [],
                    transaction_id: nil, exclude_txn_from_change_streams: false,
-                   commit_options: nil, request_options: nil, call_options: nil
+                   isolation_level: nil, commit_options: nil, request_options: nil,
+                   call_options: nil, precommit_token: nil
           route_to_leader = LARHeaders.commit
           tx_opts = nil
           if transaction_id.nil?
             tx_opts = V1::TransactionOptions.new(
               read_write: V1::TransactionOptions::ReadWrite.new,
-              exclude_txn_from_change_streams: exclude_txn_from_change_streams
+              exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+              isolation_level: isolation_level
             )
           end
           opts = default_options session_name: session_name,
@@ -549,7 +556,7 @@ module Google
           request = {
             session: session_name, transaction_id: transaction_id,
             single_use_transaction: tx_opts, mutations: mutations,
-            request_options: request_options
+            request_options: request_options, precommit_token: precommit_token
           }
 
           request = add_commit_options request, commit_options
@@ -617,24 +624,44 @@ module Google
         # @param route_to_leader [::String, nil] Optional. The value to be sent
         #   as `x-goog-spanner-route-to-leader` header for leader aware routing.
         #   Expected values: `"true"` or `"false"`.
+        # @param mutation_key [::Google::Cloud::Spanner::V1::Mutation, nil] Optional.
+        #   If a read-write transaction on a multiplexed session commit mutations
+        #   without performing any reads or queries, one of the mutations from the mutation set
+        #   must be sent as a mutation key for `BeginTransaction`.
+        # @param previous_transaction_id [::String, nil] Optional.
+        #   An id of the previous transaction, if this new transaction wrapper is being created
+        #   as a part of a retry. Previous transaction id should be added to TransactionOptions
+        #   of a new ReadWrite transaction when retry is attempted.
         # @private
         # @return [::Google::Cloud::Spanner::V1::Transaction]
         def begin_transaction session_name,
                               exclude_txn_from_change_streams: false,
                               request_options: nil,
                               call_options: nil,
-                              route_to_leader: nil
+                              route_to_leader: nil,
+                              mutation_key: nil,
+                              previous_transaction_id: nil
+          read_write = if previous_transaction_id.nil?
+                         V1::TransactionOptions::ReadWrite.new
+                       else
+                         V1::TransactionOptions::ReadWrite.new(
+                           multiplexed_session_previous_transaction_id: previous_transaction_id
+                         )
+                       end
+
           tx_opts = V1::TransactionOptions.new(
-            read_write: V1::TransactionOptions::ReadWrite.new,
+            read_write: read_write,
             exclude_txn_from_change_streams: exclude_txn_from_change_streams
           )
+
           opts = default_options session_name: session_name,
                                  call_options: call_options,
                                  route_to_leader: route_to_leader
           request = {
             session: session_name,
             options: tx_opts,
-            request_options: request_options
+            request_options: request_options,
+            mutation_key: mutation_key
           }
           service.begin_transaction request, opts
         end
@@ -657,6 +684,28 @@ module Google
           service.batch_write request, opts
         end
 
+        # Creates a specialized `V1::Transaction` object. Reads on that object will have
+        # at most one of following consistency properties:
+        # * reading all previously commited transactions
+        # * reading all data from a given timestamp
+        # * reading all data from a timestamp that is exactly a given value old
+        # (the last one sidesteps worries of client-server time skew).
+        #
+        # Having at _least_ one of those is not enforced so this can create normal transactions
+        # as well.
+        # Created transactions will include the  the read timestamp chosen for the transaction.
+        # @param session_name [::String] Required.
+        #   Required. The session in which the snapshot transaction is to be created..
+        #   Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        # @param strong [::Boolean, nil] Optional.
+        #   Whether this transaction should have strong consistency.
+        # @param timestamp [::String, ::Date ::Time, nil] Optional.
+        #   Timestamp that the reads should be executed at. Reads are repeatable with this option.
+        # @param staleness [::Numeric, nil] Optional.
+        #   The offset of staleness that the reads should be executed at.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
         def create_snapshot session_name, strong: nil, timestamp: nil,
                             staleness: nil, call_options: nil
           tx_opts = V1::TransactionOptions.new(
@@ -671,7 +720,7 @@ module Google
           )
           opts = default_options session_name: session_name,
                                  call_options: call_options
-          request = { session: session_name, options: tx_opts }
+          request = { session: session_name, options: tx_opts, mutation_key: nil }
           service.begin_transaction request, opts
         end
 
@@ -686,7 +735,7 @@ module Google
           opts = default_options session_name: session_name,
                                  call_options: call_options,
                                  route_to_leader: route_to_leader
-          request = { session: session_name, options: tx_opts }
+          request = { session: session_name, options: tx_opts, mutation_key: nil }
           service.begin_transaction request, opts
         end
 
@@ -829,6 +878,21 @@ module Google
           value << " gccl"
         end
 
+        # Creates new `Gapic::CallOptions` from typical parameters for Spanner RPC calls.
+        #
+        # @param session_name [::String, nil] Optional.
+        #   The session name. Used to extract the routing header. The value will be
+        #   used to send the old `google-cloud-resource-prefix` routing header.
+        #   Expected values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>/sessions/<session_id>`.
+        #   If nil is specified nothing will be sent.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @param route_to_leader [::String, nil] Optional. The value to be sent
+        #   as `x-goog-spanner-route-to-leader` header for leader aware routing.
+        #   Expected values: `"true"` or `"false"`. If nil is specified nothing will be sent.
+        # @private
+        # @return [::Gapic::CallOptions]
         def default_options session_name: nil, call_options: nil, route_to_leader: nil
           opts = {}
           metadata = {}