google-cloud-spanner 2.28.0 → 2.30.0

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,
@@ -530,11 +530,15 @@ module Google
         #   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
+                   commit_options: nil, request_options: nil, call_options: nil,
+                   precommit_token: nil
           route_to_leader = LARHeaders.commit
           tx_opts = nil
           if transaction_id.nil?
@@ -549,7 +553,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 +621,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 +681,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 +717,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 +732,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 +875,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 = {}

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

@@ -44,8 +44,8 @@ module Google
       #
       class Session
         # The wrapped `V1::Session` protobuf session object.
-        # @return [::Google::Cloud::Spanner::V1::Session]
         # @private
+        # @return [::Google::Cloud::Spanner::V1::Session]
         attr_accessor :grpc
 
         # The `Spanner::Service` object.
@@ -59,7 +59,7 @@ module Google
         # @return [::Hash, nil]
         attr_accessor :query_options
 
-        # Creates a new Session instance.
+        # Creates a new `Spanner::Session` instance.
         # @param grpc [::Google::Cloud::Spanner::V1::Session] Underlying `V1::Session` object.
         # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` object.
         # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
@@ -69,6 +69,7 @@ module Google
           @grpc = grpc
           @service = service
           @query_options = query_options
+          @created_time = Process.clock_gettime Process::CLOCK_MONOTONIC
         end
 
         # The unique identifier for the project.
@@ -216,6 +217,9 @@ module Google
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
         #
+        # @param precommit_token_notify [::Proc, nil] Optional.
+        #   The notification function for the precommit token.
+        #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
         #
@@ -357,7 +361,8 @@ 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, route_to_leader: nil
+                          directed_read_options: nil, route_to_leader: nil,
+                          precommit_token_notify: nil
           ensure_service!
           query_options = merge_if_present query_options, @query_options
 
@@ -373,7 +378,8 @@ module Google
 
           response = service.execute_streaming_sql path, sql, **execute_query_options
 
-          results = Results.from_execute_query_response response, service, path, sql, execute_query_options
+          results = Results.from_execute_query_response response, service, path, sql, execute_query_options,
+                                                        precommit_token_notify: precommit_token_notify
           @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           results
         end
@@ -428,8 +434,8 @@ module Google
         #   number of rows that were modified for each successful statement
         #   before the error.
         #
-        # @return [Array<Integer>] A list with the exact number of rows that
-        #   were modified for each DML statement.
+        # @return [::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse]
+        #   An unwrapped result of the service call -- a `V1::ExecuteBatchDmlResponse` object.
         #
         def batch_update transaction, seqno, request_options: nil,
                          call_options: nil
@@ -506,6 +512,9 @@ module Google
         #   To see the available options refer to
         #   ['Google::Cloud::Spanner::V1::ReadRequest::LockHint'](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-ReadRequest-LockHint)
         #
+        # @param precommit_token_notify [::Proc, nil] Optional.
+        #   The notification function for the precommit token.
+        #
         # @return [Google::Cloud::Spanner::Results] The results of the read
         #   operation.
         #
@@ -525,7 +534,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, directed_read_options: nil,
-                 route_to_leader: nil, order_by: nil, lock_hint: nil
+                 route_to_leader: nil, order_by: nil, lock_hint: nil, precommit_token_notify: nil
           ensure_service!
 
           read_options = {
@@ -544,7 +553,8 @@ module Google
           response = service.streaming_read_table \
             path, table, columns, **read_options
 
-          results = Results.from_read_response response, service, path, table, columns, read_options
+          results = Results.from_read_response response, service, path, table, columns, read_options,
+                                               precommit_token_notify: precommit_token_notify
 
           @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
 
@@ -675,12 +685,24 @@ module Google
           ensure_service!
           commit = Commit.new
           yield commit
-          commit_resp = service.commit path, commit.mutations,
-                                       transaction_id: transaction_id,
-                                       exclude_txn_from_change_streams: exclude_txn_from_change_streams,
-                                       commit_options: commit_options,
-                                       request_options: request_options,
-                                       call_options: call_options
+
+          should_retry = true
+          # @type [Google::Cloud::Spanner::V1::MultiplexedSessionPrecommitToken]
+          precommit_token = nil
+          while should_retry
+            commit_resp = service.commit(path,
+                                         commit.mutations,
+                                         transaction_id: transaction_id,
+                                         exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                                         commit_options: commit_options,
+                                         request_options: request_options,
+                                         call_options: call_options,
+                                         precommit_token: precommit_token)
+
+            precommit_token = commit_resp.precommit_token
+            should_retry = !precommit_token.nil?
+          end
+
           @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
           resp = CommitResponse.from_grpc commit_resp
           commit_options ? resp : resp.timestamp
@@ -1369,9 +1391,15 @@ module Google
           true
         end
 
-        ##
+        # Explicitly begins a new transaction and creates a server-side transaction object.
+        # Unlike {#create_empty_transaction}, this method makes an immediate
+        # `BeginTransaction` RPC call.
+        #
+        # @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.
         # @private
-        # Creates a new transaction object every time.
+        # @return [::Google::Cloud::Spanner::Transaction]
         def create_transaction exclude_txn_from_change_streams: false
           route_to_leader = LARHeaders.begin_transaction true
           tx_grpc = service.begin_transaction path,
@@ -1380,37 +1408,34 @@ module Google
           Transaction.from_grpc tx_grpc, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams
         end
 
-        ##
+        # Creates a new empty transaction wrapper without a server-side object.
+        # This is used for inline-begin transactions and does not make an RPC call.
+        # See {#create_transaction} for the RPC-based method.
+        #
+        # @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 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
-        # Creates a new transaction object without the grpc object
-        # within it. Use it for inline-begin of a transaction.
-        def create_empty_transaction exclude_txn_from_change_streams: false
-          Transaction.from_grpc nil, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams
-        end
-
-        ##
-        # Reloads the session resource. Useful for determining if the session is
-        # still valid on the Spanner API.
-        def reload!
-          ensure_service!
-          @grpc = service.get_session path
-          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
-          self
-        rescue Google::Cloud::NotFoundError
-          labels = @grpc.labels.to_h unless @grpc.labels.to_h.empty?
-          @grpc = service.create_session \
-            V1::Spanner::Paths.database_path(
-              project: project_id, instance: instance_id, database: database_id
-            ),
-            labels: labels
-          @last_updated_at = Process.clock_gettime Process::CLOCK_MONOTONIC
-          self
+        # @return [::Google::Cloud::Spanner::Transaction] The new *empty-wrapper* transaction object.
+        def create_empty_transaction exclude_txn_from_change_streams: false, previous_transaction_id: nil
+          Transaction.from_grpc nil, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+previous_transaction_id: previous_transaction_id
         end
 
-        ##
+        # If the session is non-multiplexed, keeps the session alive by executing `"SELECT 1"`.
+        # This method will re-create the session if necessary.
+        # For multiplexed session the keepalive is not required and this method immediately returns `true`.
         # @private
-        # Keeps the session alive by executing `"SELECT 1"`.
+        # @return [::Boolean]
+        #   `true` if the session is multiplexed or if the keepalive was successful for non-multiplexed session,
+        #   `false` if the non-multiplexed session was not found and the had to be recreated.
         def keepalive!
+          return true if multiplexed?
+
           ensure_service!
           route_to_leader = LARHeaders.execute_query false
           execute_query "SELECT 1", route_to_leader: route_to_leader
@@ -1425,15 +1450,19 @@ module Google
           false
         end
 
-        ##
-        # Permanently deletes the session.
+        # Permanently deletes the session unless this session is multiplexed.
+        # Multiplexed sessions can not be deleted, and this method immediately returns.
+        # @private
+        # @return [void]
         def release!
+          return if multiplexed?
           ensure_service!
           service.delete_session path
         end
 
         # Determines if the session has been idle longer than the given
-        # duration.
+        # duration in seconds.
+        #
         # @param duration_sec [::Numeric] interval in seconds
         # @private
         # @return [::Boolean]
@@ -1442,7 +1471,17 @@ module Google
           Process.clock_gettime(Process::CLOCK_MONOTONIC) > @last_updated_at + duration_sec
         end
 
-        # Creates a new Session instance from a `V1::Session`.
+        # Determines if the session did exist for at least the given
+        # duration in seconds.
+        #
+        # @param duration_sec [::Numeric] interval in seconds
+        # @private
+        # @return [::Boolean]
+        def existed_since? duration_sec
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) > @created_time + duration_sec
+        end
+
+        # Creates a new `Spanner::Session` instance from a `V1::Session` object.
         # @param grpc [::Google::Cloud::Spanner::V1::Session] Underlying `V1::Session` object.
         # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` ref.
         # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
@@ -1461,6 +1500,13 @@ module Google
 
         protected
 
+        # Whether this session is multiplexed.
+        # @private
+        # @return [::Boolean]
+        def multiplexed?
+          @grpc.multiplexed
+        end
+
         ##
         # @private Raise an error unless an active connection to the service is
         # available.