google-cloud-spanner 2.29.0 → 2.31.0

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
 
@@ -593,6 +603,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`. Used if starting a new transaction.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -671,16 +683,30 @@ module Google
         #   puts commit_resp.stats.mutation_count
         #
         def commit 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
           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,
+                                         isolation_level: isolation_level,
+                                         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
@@ -818,6 +844,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`. Used if starting a new transaction.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -890,10 +918,12 @@ module Google
         #
         def upsert table, *rows,
                    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
           opts = {
             transaction_id: transaction_id,
             exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+            isolation_level: isolation_level,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -938,6 +968,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`. Used if starting a new transaction.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1010,10 +1042,12 @@ module Google
         #
         def insert table, *rows,
                    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
           opts = {
             transaction_id: transaction_id,
             exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+            isolation_level: isolation_level,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -1057,6 +1091,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`. Used if starting a new transaction.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1129,10 +1165,12 @@ module Google
         #
         def update table, *rows,
                    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
           opts = {
             transaction_id: transaction_id,
             exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+            isolation_level: isolation_level,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -1178,6 +1216,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`. Used if starting a new transaction.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1251,10 +1291,11 @@ module Google
         #
         def replace table, *rows,
                     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
           opts = {
             transaction_id: transaction_id,
             exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+            isolation_level: isolation_level,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -1279,6 +1320,8 @@ module Google
         # @param [Boolean] exclude_txn_from_change_streams If set to true,
         #   mutations will not be recorded in change streams with DDL option
         #   `allow_txn_exclusion=true`. Used if starting a new transaction.
+        # @param [Google::Cloud::Spanner::V1::TransactionOptions::IsolationLevel] isolation_level Optional. The
+        #   isolation level for the transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1348,10 +1391,12 @@ module Google
         #
         def delete table, keys = [],
                    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
           opts = {
             transaction_id: transaction_id,
             exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+            isolation_level: isolation_level,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -1369,9 +1414,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 +1431,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 +1473,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 +1494,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 +1523,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.

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

@@ -0,0 +1,125 @@
+# Copyright 2025 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.
+
+require "concurrent"
+require "google/cloud/spanner/session"
+require "google/cloud/spanner/session_creation_options"
+
+module Google
+  module Cloud
+    module Spanner
+      # Cache for the multiplex `{Google::Cloud::Spanner::Session}` instance.
+      # @private
+      class SessionCache
+        # Time in seconds before this SessionCache will refresh the session.
+        # Counted from the session creation time (not from last usage).
+        # This is specific to multiplex sessions.
+        # The backend can keep sessions alive for quite a bit longer (28 days) but
+        # we perform refresh after 7 days.
+        # @private
+        SESSION_REFRESH_SEC = 7 * 24 * 3600
+
+        # Create a single-session "cache" for multiplex sessions.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @param session_creation_options [::Google::Cloud::Spanner::SessionCreationOptions] Required.
+        # @private
+        def initialize service, session_creation_options
+          @service = service
+          @session_creation_options = session_creation_options
+          @mutex = Mutex.new
+          @session = nil
+        end
+
+        # Yields the current session to run an operation (or a series of operations) on.
+        # @yield session A session to run requests on
+        # @yieldparam session [::Google::Cloud::Spanner::Session]
+        # @private
+        # @yieldreturn [::Object] The result of the operation that ran on a session.
+        # @return [::Object] The value returned by the yielded block.
+        def with_session
+          ensure_session!
+          yield @session
+        end
+
+        # Re-initializes the session in the session cache.
+        # @private
+        # @return [::Boolean]
+        def reset!
+          @mutex.synchronize do
+            @session = create_new_session
+          end
+
+          true
+        end
+
+        # Closes the pool. This is a NOP for Multiplex Session Cache since
+        # multiplex sessions don't require cleanup.
+        # @private
+        # @return [::Boolean]
+        def close
+          true
+        end
+
+        # Returns the current session. For use in the `{Spanner::BatchClient}`
+        # where usage pattern is incompatible with `with_session`.
+        # For other uses please use `with_session` instead.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
+        def session
+          ensure_session!
+          @session
+        end
+
+        private
+
+        # Ensures that a single session exists and is current.
+        # @private
+        # @return [nil]
+        def ensure_session!
+          return unless @session.nil? || @session.existed_since?(SESSION_REFRESH_SEC)
+
+          @mutex.synchronize do
+            return unless @session.nil? || @session.existed_since?(SESSION_REFRESH_SEC)
+            @session = create_new_session
+          end
+
+          nil
+        end
+
+        # Creates a new multiplexed `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,
+            multiplexed: true
+          )
+
+          Session.from_grpc grpc, @service, query_options: @session_creation_options.query_options
+        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
+end

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

@@ -0,0 +1,70 @@
+# Copyright 2025 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
+      # Options for creating new sessions that clients use
+      # to parametrize Pool and SessionCache.
+      # Example: session labels.
+      # @private
+      class SessionCreationOptions
+        # The full path to the Spanner database. Values are of the form:
+        # `projects/<project_id>/instances/<instance_id>/databases/<database_id>.
+        # @private
+        # @return [::String]
+        attr_reader :database_path
+
+        # The labels to be applied to all sessions created by the client.
+        # Optional. Example: `"team" => "billing-service"`.
+        # @private
+        # @return [::Hash, nil]
+        attr_reader :session_labels
+
+        # The Spanner session creator role.
+        # Optional. Example: `analyst`.
+        # @return [::String, nil]
+        attr_reader :session_creator_role
+
+        # A hash of values to specify the custom query options for executing SQL query.
+        # Optional. Example option: `:optimizer_version`.
+        # @private
+        # @return [::Hash, nil]
+        attr_reader :query_options
+
+        # Creates a new SessionCreationOptions object.
+        # @param database_path [::String]
+        #   The full path to the Spanner database. Values are of the form:
+        #   `projects/<project_id>/instances/<instance_id>/databases/<database_id>.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param session_creator_role [::String, nil] Optional. The Spanner session creator role.
+        #   Example: `analyst`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example option: `:optimizer_version`.
+        # @private
+        def initialize database_path:, session_labels: nil, session_creator_role: nil, query_options: nil
+          if database_path.nil? || database_path.empty?
+            raise ArgumentError, "database_path is required for session creation options"
+          end
+
+          @database_path = database_path
+          @session_labels = session_labels
+          @session_creator_role = session_creator_role
+          @query_options = query_options
+        end
+      end
+    end
+  end
+end

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

@@ -41,9 +41,26 @@ module Google
       #   end
       #
       class Snapshot
-        # @private The Session object.
+        # A `V1::Session` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::Session]
         attr_accessor :session
 
+        # Creates a new `Spanner::Snapshot` instance.
+        # @param grpc [::Google::Cloud::Spanner::V1::Transaction]
+        #   Underlying `V1::Transaction` object.
+        # @param session [::Google::Cloud::Spanner::Session] A `Spanner::Session` reference.
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Snapshot]
+        def initialize grpc, session, directed_read_options: nil
+          @grpc = grpc
+          @session = session
+          @directed_read_options = directed_read_options
+        end
+
         ##
         # Identifier of the transaction results were run in.
         # @return [String] The transaction id.
@@ -536,15 +553,18 @@ module Google
                     exclude_end: exclude_end
         end
 
-        ##
-        # @private Creates a new Snapshot instance from a
+        # Creates a new `Spanner::Snapshot` instance from a
         # `Google::Cloud::Spanner::V1::Transaction`.
-        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
+        # @param grpc [::Google::Cloud::Spanner::V1::Transaction]
+        #   Underlying `V1::Transaction` object.
+        # @param session [::Google::Cloud::Spanner::Session] A `Spanner::Session` reference.
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
+        # @return [::Google::Cloud::Spanner::Snapshot]
+        def self.from_grpc grpc, session, directed_read_options: nil
+          new grpc, session, directed_read_options: directed_read_options
         end
 
         protected