google-cloud-spanner 2.21.0 → 2.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b4512d4772029fbc6c9ea89195d788ddd6cb0ecb06568764ada121e37b0afe5
-  data.tar.gz: acd1c491242e6c656eb8cff2ad1ec09749e4895a3badb828d58eb7db98a65760
+  metadata.gz: 32575eadb5e1598ba5b49fc7dc27cc70e2d6f370c52aa42cdad5e9fa3059cf41
+  data.tar.gz: b5bec492eed277a46d4f4031e7f9ef9ef40472df57f747a1ea88266b397fafca
 SHA512:
-  metadata.gz: cd930852601a8ec5fb036662ad7fae03a99d5a0e9e7e566d689113d60bb62f90af4ba35da1856bdcee6a1ba147ad6f6e5a4701c37c0b59c0d371e43a25b93ec7
-  data.tar.gz: 7cabba248fda38947ebaf27f45b6bacf25ff14e770fcfabe76d6b66dc57c6e572aa82eb8b8bb1d4ed068036805e8f5cff56b5bc8cc553bd4921f75ac1e4a8b0d
+  metadata.gz: c826d09f5ff0abe190d1f51a942f120ee67b032b508edba22de82b42b079e8c833ed7e044570c5f1138c0d4e85aeb9fb3d93d571ce5db8deca898f0d456cf267
+  data.tar.gz: e06690d05125c1af27c8fb2e5f29f0b75b1a2d9eecd31fa6865e80fc0592caba84bc2cdb864ff25bd18a8b333019fabb52f13647b42521acf0c0706049bbc0f5

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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
+
+* Support FLOAT32 datatype ([#94](https://github.com/googleapis/ruby-spanner/issues/94)) 
+* Update minimum Ruby version to 2.7 ([#89](https://github.com/googleapis/ruby-spanner/issues/89)) 
+#### Bug Fixes
+
+* Use https in Gemfile to avoid security vulnerability ([#95](https://github.com/googleapis/ruby-spanner/issues/95)) 
+
 ### 2.21.0 (2024-02-07)
 
 #### 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_client.rb

@@ -196,8 +196,8 @@ module Google
           snp_session = session
           snp_grpc = @project.service.create_snapshot \
             snp_session.path, strong: strong,
-                              timestamp: (timestamp || read_timestamp),
-                              staleness: (staleness || exact_staleness)
+                              timestamp: timestamp || read_timestamp,
+                              staleness: staleness || exact_staleness
           BatchSnapshot.from_grpc snp_grpc, snp_session, directed_read_options: @directed_read_options
         end
 
@@ -306,6 +306,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:INT64`
         #   * `:STRING`
         #   * `:TIMESTAMP`

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).
@@ -128,6 +129,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
         #   | `TIMESTAMP` | `Time`, `DateTime` | |
@@ -153,6 +155,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:INT64`
         #   * `:STRING`
         #   * `:TIMESTAMP`
@@ -255,7 +258,7 @@ module Google
                 partition_token: grpc.partition_token,
                 query_options: query_options,
                 data_boost_enabled: data_boost_enabled,
-                directed_read_options: (directed_read_options || @directed_read_options)
+                directed_read_options: directed_read_options || @directed_read_options
               }.compact
             )
             Partition.from_execute_sql_grpc execute_sql_grpc
@@ -365,7 +368,7 @@ module Google
                 transaction: tx_selector,
                 partition_token: grpc.partition_token,
                 data_boost_enabled: data_boost_enabled,
-                directed_read_options: (directed_read_options || @directed_read_options)
+                directed_read_options: directed_read_options || @directed_read_options
               }.compact
             )
             Partition.from_read_grpc read_grpc
@@ -477,6 +480,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
         #   | `TIMESTAMP` | `Time`, `DateTime` | |
@@ -502,6 +506,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:INT64`
         #   * `:STRING`
         #   * `:TIMESTAMP`
@@ -704,7 +709,7 @@ module Google
                                 transaction: tx_selector,
                                 query_options: query_options,
                                 call_options: call_options,
-                                directed_read_options: (directed_read_options || @directed_read_options)
+                                directed_read_options: directed_read_options || @directed_read_options
         end
         alias execute execute_query
         alias query execute_query
@@ -780,7 +785,7 @@ module Google
           session.read table, columns, keys: keys, index: index, limit: limit,
                                        transaction: tx_selector,
                                        call_options: call_options,
-                                       directed_read_options: (directed_read_options || @directed_read_options)
+                                       directed_read_options: directed_read_options || @directed_read_options
         end
 
         ##

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

@@ -59,6 +59,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
         #   | `TIMESTAMP` | `Time`, `DateTime` | |
@@ -85,6 +86,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:INT64`
         #   * `:STRING`
         #   * `:TIMESTAMP`
@@ -153,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