google-cloud-spanner 2.22.0 → 2.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 513a3295d6e11b7e4550647a7aad81ac3d52d4ea3e758d79eb39c7d62a2c7202
-  data.tar.gz: a86f44421150171474e3335af0fa82712e26387c5ecb12051ea6d3b661a2c310
+  metadata.gz: 32575eadb5e1598ba5b49fc7dc27cc70e2d6f370c52aa42cdad5e9fa3059cf41
+  data.tar.gz: b5bec492eed277a46d4f4031e7f9ef9ef40472df57f747a1ea88266b397fafca
 SHA512:
-  metadata.gz: b57e293bd3a352475fa1a57177dd54c153240850df552b230088c13fa5222916391dd17b36cb06817f214bd067b457ae0a66a638e30d7a364d1467e76cd70a1e
-  data.tar.gz: a91b6efe6724f1f3a2e8b77fb2c85918bfe3b732bf17dc52b8728db9c10e1f18bde501dd09a08af24fd29f8297c4206cdbac3cdbb18427b21d97f2af584ecd81
+  metadata.gz: c826d09f5ff0abe190d1f51a942f120ee67b032b508edba22de82b42b079e8c833ed7e044570c5f1138c0d4e85aeb9fb3d93d571ce5db8deca898f0d456cf267
+  data.tar.gz: e06690d05125c1af27c8fb2e5f29f0b75b1a2d9eecd31fa6865e80fc0592caba84bc2cdb864ff25bd18a8b333019fabb52f13647b42521acf0c0706049bbc0f5

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Release History
 
+### 2.23.0 (2024-06-27)
+
+#### Features
+
+* Support BatchWrite API ([#99](https://github.com/googleapis/ruby-spanner/issues/99)) 
+* Support exclude_txn_from_change_streams ([#108](https://github.com/googleapis/ruby-spanner/issues/108)) 
+#### Bug Fixes
+
+* Resolve BigDecimal warning in Ruby 3.4 ([#103](https://github.com/googleapis/ruby-spanner/issues/103)) 
+#### Documentation
+
+* Update documentation regarding root partitionability ([#101](https://github.com/googleapis/ruby-spanner/issues/101)) 
+
 ### 2.22.0 (2024-04-01)
 
 #### Features

data/lib/google/cloud/spanner/admin/database.rb

@@ -20,6 +20,8 @@ module Google
     module Spanner
       module Admin
         module Database
+          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
+
           ##
           # Create a new client object for a DatabaseAdmin.
           #
@@ -81,7 +83,6 @@ module Google
           #
           # @return [Admin::Database::V1::DatabaseAdmin::Client] A client object of version V1.
           #
-          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
           def self.database_admin project_id: nil,
                                   credentials: nil,
                                   scope: nil,
@@ -135,16 +136,6 @@ module Google
           # Configure the Google Cloud Spanner Database Admin library. This configuration can be
           # applied globally to all clients.
           #
-          # @example
-          #
-          # Modify the global config, setting the timeout to 10 seconds for all admin databases.
-          #
-          # require "google/cloud/spanner/admin/database"
-          #
-          # ::Google::Cloud::Spanner::Admin::Database.configure do |config|
-          #   config.timeout = 10.0
-          # end
-          #
           # The following configuration parameters are supported:
           #
           # * `credentials` (*type:* `String, Hash, Google::Auth::Credentials`) -
@@ -172,6 +163,13 @@ module Google
           #
           # @return [::Google::Cloud::Config] The default configuration used by this library
           #
+          # @example Modify the global config, setting the timeout to 10 seconds for all admin databases.
+          #   require "google/cloud/spanner/admin/database"
+          #
+          #   ::Google::Cloud::Spanner::Admin::Database.configure do |config|
+          #     config.timeout = 10.0
+          #   end
+          #
           def self.configure
             @configure ||= begin
               namespace = ["Google", "Cloud", "Spanner"]

data/lib/google/cloud/spanner/admin/instance.rb

@@ -21,6 +21,8 @@ module Google
     module Spanner
       module Admin
         module Instance
+          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
+
           ##
           # Create a new client object for a InstanceAdmin.
           #
@@ -81,7 +83,6 @@ module Google
           #
           # @return [Admin::Instance::V1::InstanceAdmin::Client] A client object of version V1.
           #
-          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
           def self.instance_admin project_id: nil,
                                   credentials: nil,
                                   scope: nil,
@@ -135,16 +136,6 @@ module Google
           # Configure the Google Cloud Spanner Instance Admin library. This configuration can be
           # applied globally to all clients.
           #
-          # @example
-          #
-          # Modify the global config, setting the timeout to 10 seconds for all admin instances.
-          #
-          # require "google/cloud/spanner/admin/instance"
-          #
-          # ::Google::Cloud::Spanner::Admin::Instance.configure do |config|
-          #   config.timeout = 10.0
-          # end
-          #
           # The following configuration parameters are supported:
           #
           # * `credentials` (*type:* `String, Hash, Google::Auth::Credentials`) -
@@ -172,6 +163,13 @@ module Google
           #
           # @return [::Google::Cloud::Config] The default configuration used by this library
           #
+          # @example Modify the global config, setting the timeout to 10 seconds for all admin instances.
+          #   require "google/cloud/spanner/admin/instance"
+          #
+          #   ::Google::Cloud::Spanner::Admin::Instance.configure do |config|
+          #     config.timeout = 10.0
+          #   end
+          #
           def self.configure
             @configure ||= begin
               namespace = ["Google", "Cloud", "Spanner"]

data/lib/google/cloud/spanner/backup/job/list.rb

@@ -30,8 +30,7 @@ module Google
           # operations.
           #
           # @deprecated Use the result of
-          # {Google::Cloud::Spanner::Admin::Database#database_admin Client#list_backup_operations}
-          # instead.
+          #   {Google::Cloud::Spanner::Admin::Database.database_admin}.list_backup_operations instead.
           #
           class List < DelegateClass(::Array)
             # @private

data/lib/google/cloud/spanner/backup/job.rb

@@ -36,8 +36,7 @@ module Google
         #   Long-running Operation
         #
         # @deprecated Use the long-running operation returned by
-        # {Google::Cloud::Spanner::Admin::Database#database_admin Client#create_backup}
-        # instead.
+        #   {Google::Cloud::Spanner::Admin::Database.database_admin}.create_backup instead.
         #
         # @example
         #   require "google/cloud/spanner"

data/lib/google/cloud/spanner/backup/list.rb

@@ -28,9 +28,7 @@ module Google
         # Google::Cloud::Spanner::Backup::List is a special case Array with
         # additional values.
         #
-        # @deprecated Use the result of
-        # {Google::Cloud::Spanner::Admin::Database#database_admin Client#list_backups}
-        # instead.
+        # @deprecated Use the result of {Google::Cloud::Spanner::Admin::Database.database_admin}.list_backups instead.
         #
         class List < DelegateClass(::Array)
           # @private

data/lib/google/cloud/spanner/backup/restore/job.rb

@@ -36,8 +36,7 @@ module Google
           #   Long-running Operation
           #
           # @deprecated Use the long-running operation returned by
-          # {Google::Cloud::Spanner::Admin::Database#database_admin Client#restore_database}
-          # instead.
+          #   {Google::Cloud::Spanner::Admin::Database.database_admin}.restore_database instead.
           #
           # @example
           #   require "google/cloud/spanner"

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

@@ -101,12 +101,13 @@ module Google
         # configured, although the values given may not necessarily be honored
         # depending on the query and options in the request.
         #
-        # The query must have a single [distributed
+        # The request will fail if the query is not root partitionable. For a
+        # query to be root partitionable, it needs to satisfy a few conditions.
+        # For example, if the query execution plan contains a [distributed
         # union](https://cloud.google.com/spanner/docs/query-execution-operators#distributed_union)
-        # operator at the root of the query plan. Such queries are
-        # root-partitionable. If a query cannot be partitioned at the root,
-        # Cloud Spanner cannot achieve the parallelism and in this case
-        # partition generation will fail.
+        # operator, then it must be the first operator in the plan. For more
+        # information about other conditions, see [Read data in
+        # parallel](https://cloud.google.com/spanner/docs/reads#read_data_in_parallel).
         #
         # @param [String] sql The SQL query string. See [Query
         #   syntax](https://cloud.google.com/spanner/docs/query-syntax).

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

@@ -155,8 +155,7 @@ module Google
           end
 
           def to_grpc
-            converted_params, converted_types = \
-              Convert.to_input_params_and_types params, types
+            converted_params, converted_types = Convert.to_input_params_and_types params, types
             # param_types is a grpc map field, can't be nil
             converted_types ||= {}
             V1::ExecuteBatchDmlRequest::Statement.new(

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

@@ -0,0 +1,72 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "google/cloud/spanner/mutation_group"
+require "google/cloud/spanner/v1"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # Part of the BatchWrite DSL.
+      #
+      # This object is passed as a parameter to the block passed to
+      # {Google::Cloud::Spanner::Client#batch_write}. Use this parameter to add
+      # mutation groups to the batch.
+      #
+      class BatchWrite
+        # @private
+        def initialize
+          @mutation_groups = []
+        end
+
+        ##
+        # Adds a group of mutations
+        #
+        # @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
+        #
+        def mutation_group
+          mg = MutationGroup.new
+          yield mg
+          @mutation_groups << mg
+        end
+
+        # @private
+        def mutation_groups_grpc
+          @mutation_groups.map do |mg|
+            Google::Cloud::Spanner::V1::BatchWriteRequest::MutationGroup.new mutations: mg.mutations
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "google/cloud/errors"
+require "google/cloud/spanner/convert"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # Results of a batch write.
+      #
+      # This is a stream of {BatchWriteResults::BatchResult} objects, each of
+      # which represents a set of mutation groups applied together.
+      #
+      # Use the Ruby Enumerable module to iterate over the results.
+      #
+      class BatchWriteResults
+        ##
+        # Result of a set of mutation groups applied together.
+        #
+        class BatchResult
+          # @private
+          def initialize grpc
+            @grpc = grpc
+          end
+
+          ##
+          # The indexes of the mutation groups applied together.
+          #
+          # @return [::Array<::Integer>]
+          #
+          def indexes
+            @grpc.indexes.to_a
+          end
+
+          ##
+          # The result of this set of mutation groups.
+          #
+          # @return [::Google::Rpc::Status]
+          #
+          def status
+            @grpc.status
+          end
+
+          ##
+          # Whether these mutation groups were successful.
+          #
+          # @return [::Boolean]
+          #
+          def ok?
+            status.code.zero?
+          end
+
+          ##
+          # Whether these mutation groups were unsuccessful.
+          #
+          # @return [::Boolean]
+          #
+          def error?
+            !ok?
+          end
+
+          ##
+          # The timestamp of the commit.
+          #
+          # @return [::Time]
+          #
+          def commit_timestamp
+            Convert.timestamp_to_time @grpc.commit_timestamp
+          end
+        end
+
+        # @private
+        def initialize enum
+          @enumerable = enum
+        end
+
+        ##
+        # Iterate over the results.
+        #
+        # @yield [::Google::Cloud::Spanner::BatchWriteResults::BatchResult]
+        #
+        def each &block
+          if defined? @results
+            @results.each(&block)
+          else
+            results = []
+            @enumerable.each do |grpc|
+              result = BatchResult.new grpc
+              results << result
+              yield result
+            end
+            @results = results
+          end
+        rescue GRPC::BadStatus => e
+          raise Google::Cloud::Error.from_error(e)
+        end
+
+        include Enumerable
+
+        ##
+        # Whether all mutation groups were successful.
+        #
+        # @return [::Boolean]
+        #
+        def ok?
+          all?(&:ok?)
+        end
+
+        ##
+        # Whether at least one mutation group encountered an error.
+        #
+        # @return [::Boolean]
+        #
+        def error?
+          !ok?
+        end
+
+        ##
+        # A list of the indexes of successful mutation groups.
+        #
+        # @return [::Array<::Integer>]
+        #
+        def successful_indexes
+          flat_map { |batch_result| batch_result.ok? ? batch_result.indexes : [] }
+        end
+      end
+    end
+  end
+end