google-cloud-spanner 2.22.0 → 2.24.0

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

@@ -18,6 +18,7 @@ require "google/cloud/spanner/results"
 require "google/cloud/spanner/commit"
 require "google/cloud/spanner/commit_response"
 require "google/cloud/spanner/batch_update"
+require "google/cloud/spanner/batch_write"
 
 module Google
   module Cloud
@@ -564,6 +565,9 @@ module Google
         # @param [String] transaction_id The identifier of previously-started
         #   transaction to be used instead of starting a new transaction.
         #   Optional.
+        # @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 [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -641,13 +645,14 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def commit transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def commit transaction_id: nil, exclude_txn_from_change_streams: false,
+                   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
@@ -656,6 +661,103 @@ module Google
           commit_options ? resp : resp.timestamp
         end
 
+        ##
+        # Batches the supplied mutation groups in a collection of efficient
+        # transactions.
+        #
+        # All mutations in a group are committed atomically. However, mutations
+        # across groups can be committed non-atomically in an unspecified order
+        # and thus they must be independent of each other. Partial failure is
+        # possible, i.e., some groups may have been committed successfully,
+        # while others may have failed. The results of individual batches are
+        # streamed into the response as the batches are applied.
+        #
+        # BatchWrite requests are not replay protected, meaning that each mutation
+        # group may be applied more than once. Replays of non-idempotent mutations
+        # may have undesirable effects. For example, replays of an insert mutation
+        # may produce an already exists error or if you use generated or commit
+        # timestamp-based keys, it may result in additional rows being added to the
+        # mutation's table. We recommend structuring your mutation groups to be
+        # idempotent to avoid this issue.
+        #
+        # @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`.
+        # @param [Hash] request_options Common request options.
+        #
+        #   * `:priority` (String) The relative priority for requests.
+        #     The priority acts as a hint to the Cloud Spanner scheduler
+        #     and does not guarantee priority or order of execution.
+        #     Valid values are `:PRIORITY_LOW`, `:PRIORITY_MEDIUM`,
+        #     `:PRIORITY_HIGH`. If priority not set then default is
+        #     `PRIORITY_UNSPECIFIED` is equivalent to `:PRIORITY_HIGH`.
+        #   * `:tag` (String) A per-request tag which can be applied to
+        #     queries or reads, used for statistics collection. Tag must be a
+        #     valid identifier of the form: `[a-zA-Z][a-zA-Z0-9_\-]` between 2
+        #     and 64 characters in length.
+        #
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
+        # @yield [batch_write] a batch write object
+        # @yieldparam [Google::Cloud::Spanner::BatchWrite] batch_write a batch
+        #   write object used to add mutaion groups through {MutationGroup}.
+        #
+        # @return [Google::Cloud::Spanner::BatchWriteResults] The results of
+        #   the batch write operation. This is a stream of responses, each
+        #   covering a set of the mutation groups that were either applied or
+        #   failed together.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.batch_write do |b|
+        #     # First mutation group
+        #     b.mutation_group do |mg|
+        #       mg.upsert "Singers", [{ SingerId: 16, FirstName: "Charlie", LastName: "Terry" }]
+        #     end
+        #
+        #     # Second mutation group
+        #     b.mutation_group do |mg|
+        #       mg.upsert "Singers", [{ SingerId: 17, FirstName: "Catalina", LastName: "Smith" }]
+        #       mg.update "Albums", [{ SingerId: 17, AlbumId: 1, AlbumTitle: "Go Go Go" }]
+        #     end
+        #   end
+        #
+        #   results.each do |response|
+        #     puts "groups applied: #{response.indexes}" if response.ok?
+        #   end
+        #
+        def batch_write exclude_txn_from_change_streams: false,
+                        request_options: nil,
+                        call_options: nil
+          ensure_service!
+          b = BatchWrite.new
+          yield b
+          response = service.batch_write path, b.mutation_groups_grpc,
+                                         exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                                         request_options: request_options,
+                                         call_options: call_options
+          results = BatchWriteResults.new response
+          @last_updated_at = Time.now
+          results
+        end
+
         ##
         # Inserts or updates rows in a table. If any of the rows already exist,
         # then its column values are overwritten with the ones provided. Any
@@ -685,6 +787,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @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 [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -755,10 +863,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def upsert table, *rows, transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def upsert table, *rows,
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             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
@@ -797,6 +907,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @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 [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -867,10 +983,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def insert table, *rows, transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def insert table, *rows,
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             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
@@ -908,6 +1026,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @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 [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -978,10 +1102,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def update table, *rows, transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def update table, *rows,
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             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
@@ -1021,6 +1147,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @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 [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1092,10 +1224,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def replace table, *rows, transaction_id: nil, commit_options: nil,
-                    request_options: nil, call_options: nil
+        def replace table, *rows,
+                    transaction_id: nil, exclude_txn_from_change_streams: false,
+                    commit_options: nil, request_options: nil, call_options: nil
           opts = {
             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
@@ -1114,6 +1248,12 @@ module Google
         # @param [Object, Array<Object>] keys A single, or list of keys or key
         #   ranges to match returned data to. Values should have exactly as many
         #   elements as there are columns in the primary key.
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @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 [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1181,10 +1321,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def delete table, keys = [], transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def delete table, keys = [],
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             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
@@ -1205,18 +1347,20 @@ module Google
         ##
         # @private
         # Creates a new transaction object every time.
-        def create_transaction
+        def create_transaction exclude_txn_from_change_streams: false
           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
+          tx_grpc = service.begin_transaction path,
+                                              route_to_leader: route_to_leader,
+                                              exclude_txn_from_change_streams: exclude_txn_from_change_streams
+          Transaction.from_grpc tx_grpc, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams
         end
 
         ##
         # @private
         # Creates a new transaction object without the grpc object
         # within it. Use it for inline-begin of a transaction.
-        def create_empty_transaction
-          Transaction.from_grpc nil, self
+        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
 
         ##

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

@@ -85,9 +85,13 @@ module Google
         # @private Transaction tag for statistics collection.
         attr_accessor :transaction_tag
 
+        # @private Whether to exclude from change streams.
+        attr_accessor :exclude_txn_from_change_streams
+
         def initialize
           @commit = Commit.new
           @seqno = 0
+          @exclude_txn_from_change_streams = false
 
           # Mutex to enfore thread safety for transaction creation and query executions.
           #
@@ -1152,10 +1156,11 @@ module Google
         ##
         # @private Creates a new Transaction instance from a
         # `Google::Cloud::Spanner::V1::Transaction`.
-        def self.from_grpc grpc, session
+        def self.from_grpc grpc, session, exclude_txn_from_change_streams: false
           new.tap do |s|
             s.instance_variable_set :@grpc,    grpc
             s.instance_variable_set :@session, session
+            s.exclude_txn_from_change_streams = exclude_txn_from_change_streams
           end
         end
 
@@ -1216,11 +1221,12 @@ module Google
         #
         #   This method is expected to be called from within `safe_execute()` method's block,
         #   since it provides synchronization and gurantees thread safety.
-        def tx_selector
+        def tx_selector exclude_txn_from_change_streams: false
           return V1::TransactionSelector.new id: transaction_id if existing_transaction?
           V1::TransactionSelector.new(
             begin: V1::TransactionOptions.new(
-              read_write: V1::TransactionOptions::ReadWrite.new
+              read_write: V1::TransactionOptions::ReadWrite.new,
+              exclude_txn_from_change_streams: exclude_txn_from_change_streams
             )
           )
         end

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.22.0
+  version: 2.24.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,78 +9,110 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-04-01 00:00:00.000000000 Z
+date: 2024-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: google-cloud-core
+  name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: google-cloud-spanner-admin-database-v1
+  name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: google-cloud-spanner-admin-instance-v1
+  name: google-cloud-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
-  name: google-cloud-spanner-v1
+  name: google-cloud-spanner-admin-database-v1
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.19.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 2.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.19.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 2.a
 - !ruby/object:Gem::Dependency
-  name: concurrent-ruby
+  name: google-cloud-spanner-admin-instance-v1
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 0.16.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 0.16.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
+- !ruby/object:Gem::Dependency
+  name: google-cloud-spanner-v1
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.27.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.27.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
 description: google-cloud-spanner is the official library for Google Cloud Spanner
   API.
 email:
@@ -114,6 +146,8 @@ files:
 - lib/google/cloud/spanner/batch_snapshot.rb
 - lib/google/cloud/spanner/batch_update.rb
 - lib/google/cloud/spanner/batch_update_results.rb
+- lib/google/cloud/spanner/batch_write.rb
+- lib/google/cloud/spanner/batch_write_results.rb
 - lib/google/cloud/spanner/client.rb
 - lib/google/cloud/spanner/column_value.rb
 - lib/google/cloud/spanner/commit.rb
@@ -136,6 +170,7 @@ files:
 - 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/mutation_group.rb
 - lib/google/cloud/spanner/partition.rb
 - lib/google/cloud/spanner/policy.rb
 - lib/google/cloud/spanner/pool.rb