google-cloud-spanner 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01dd371ff37296529b691fd13961d7e7681e63480a88202b9e958a8c28bc480b
-  data.tar.gz: 9915fdf52be7508c55380b193a9586a35c702617080d3bf93a9f53b37b62be84
+  metadata.gz: 62f5ce383d6aefe48214924e77b5a794bd0a0c03bb6acaedd383be12d47da9b9
+  data.tar.gz: ed1e49a6ef47946d557f8cb768d6da33923179fa05551ea7fadd55f3f5cfe341
 SHA512:
-  metadata.gz: 0a34c4eeaaf84abe4d311350a155b22190c7dbc426a48719df4ad553692d841aa1a2d3a72d7f043b2fef7b3fa87a81cda69f965f5eef58a8ce17a77bf186a48e
-  data.tar.gz: 36062397079b8960916575b9188c0ad10f376d27b7d194a20e7f4c6e69f29eeb018b499576209bf1b2d2985725233db5de3e233ff840b5c93790d15b9b4204ab
+  metadata.gz: 4b22e83c54208f8961e267a81ef681f98ef7e2ffe9a48274e566899adfed7c514c3a124b9f747667908db89067cbe0715f8c1363635d75cd4461f9072f703819
+  data.tar.gz: '085550ca4945d0436fd92f94adb16464d30224f5f466ca1f3becb24bdcf0b8bc4fa0416d2f26ecc375ca71eadface1856702dac02a7093bda001ce4e37be359d'

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 2.3.0 / 2021-02-09
+
+#### Features
+
+* CommitStats in CommitResponse ([#8058](https://www.github.com/googleapis/google-cloud-ruby/issues/8058))
+* optionalize `credentials` when using cloud spanner emulator host ([#8416](https://www.github.com/googleapis/google-cloud-ruby/issues/8416))
+  * Optionalize `credentials` when using Cloud Spanner Emulator
+  * Remove unnecessary credentials stub for emulator_host in Google::Cloud::Spanner.new
+  * Add test of explicit project_id in Google::Cloud::Spanner.new
+  * Update document for `emulator_host` without credentials
+  * Tidy code according to rubocop settings
+
 ### 2.2.0 / 2020-09-15
 
 #### Features

data/CONTRIBUTING.md

@@ -45,7 +45,7 @@ there is a small amount of setup:
 
    ```sh
    $ cd google-cloud-spanner/
-   $ bundle exec rake bundleupdate
+   $ bundle install
    ```
 
 ## Console

data/lib/google/cloud/spanner.rb

@@ -49,6 +49,8 @@ module Google
       # @param [String, Hash, Google::Auth::Credentials] credentials The path to
       #   the keyfile as a String, the contents of the keyfile as a Hash, or a
       #   Google::Auth::Credentials object. (See {Spanner::Credentials})
+      #   If `emulator_host` is present, this becomes optional and the value is
+      #   internally overriden with `:this_channel_is_insecure`.
       # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
       #   See [Using OAuth 2.0 to Access Google
@@ -60,7 +62,7 @@ module Google
       #   * `https://www.googleapis.com/auth/spanner.data`
       # @param [Integer] timeout Default timeout to use in requests. Optional.
       # @param [String] endpoint Override of the endpoint host name. Optional.
-      #   If the param is nil, uses the default endpoint.
+      #   If the param is nil, uses `emulator_host` or the default endpoint.
       # @param [String] project Alias for the `project_id` argument. Deprecated.
       # @param [String] keyfile Alias for the `credentials` argument.
       #   Deprecated.
@@ -91,19 +93,19 @@ module Google
       def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
                    endpoint: nil, project: nil, keyfile: nil,
                    emulator_host: nil, lib_name: nil, lib_version: nil
-        project_id    ||= (project || default_project_id)
+        project_id    ||= project || default_project_id
         scope         ||= configure.scope
         timeout       ||= configure.timeout
-        endpoint      ||= configure.endpoint
-        credentials   ||= (keyfile || default_credentials(scope: scope))
         emulator_host ||= configure.emulator_host
+        endpoint      ||= emulator_host || configure.endpoint
+        credentials   ||= keyfile
         lib_name      ||= configure.lib_name
         lib_version   ||= configure.lib_version
 
         if emulator_host
           credentials = :this_channel_is_insecure
-          endpoint = emulator_host
         else
+          credentials ||= default_credentials scope: scope
           unless credentials.is_a? Google::Auth::Credentials
             credentials = Spanner::Credentials.new credentials, scope: scope
           end

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

@@ -23,6 +23,7 @@ require "google/cloud/spanner/snapshot"
 require "google/cloud/spanner/range"
 require "google/cloud/spanner/column_value"
 require "google/cloud/spanner/convert"
+require "google/cloud/spanner/commit_response"
 
 module Google
   module Cloud
@@ -809,7 +810,16 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -821,9 +831,24 @@ module Google
         #   db.upsert "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def upsert table, *rows
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.upsert "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def upsert table, rows, commit_options: nil
           @pool.with_session do |session|
-            session.upsert table, rows
+            session.upsert table, rows, commit_options: commit_options
           end
         end
         alias save upsert
@@ -865,7 +890,16 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -877,9 +911,24 @@ module Google
         #   db.insert "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def insert table, *rows
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.insert "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def insert table, rows, commit_options: nil
           @pool.with_session do |session|
-            session.insert table, rows
+            session.insert table, rows, commit_options: commit_options
           end
         end
 
@@ -920,7 +969,16 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -932,9 +990,24 @@ module Google
         #   db.update "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def update table, *rows
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.update "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def update table, rows, commit_options: nil
           @pool.with_session do |session|
-            session.update table, rows
+            session.update table, rows, commit_options: commit_options
           end
         end
 
@@ -977,7 +1050,16 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -989,9 +1071,24 @@ module Google
         #   db.replace "users", [{ id: 1, name: "Charlie", active: false },
         #                        { id: 2, name: "Harvey",  active: true }]
         #
-        def replace table, *rows
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.replace "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def replace table, rows, commit_options: nil
           @pool.with_session do |session|
-            session.replace table, rows
+            session.replace table, rows, commit_options: commit_options
           end
         end
 
@@ -1015,6 +1112,14 @@ 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 [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
         # @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:
@@ -1029,7 +1134,8 @@ module Google
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -1040,9 +1146,23 @@ module Google
         #
         #   db.delete "users", [1, 2, 3]
         #
-        def delete table, keys = [], call_options: nil
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.delete "users", [1, 2, 3], commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def delete table, keys = [], commit_options: nil, call_options: nil
           @pool.with_session do |session|
-            session.delete table, keys, call_options: call_options
+            session.delete table, keys, commit_options: commit_options,
+                           call_options: call_options
           end
         end
 
@@ -1061,6 +1181,14 @@ module Google
         # this method may be appropriate for latency sensitive and/or high
         # throughput blind changes.
         #
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
         # @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:
@@ -1078,7 +1206,8 @@ module Google
         # @yield [commit] The block for mutating the data.
         # @yieldparam [Google::Cloud::Spanner::Commit] commit The Commit object.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -1092,15 +1221,34 @@ module Google
         #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
         #   end
         #
-        def commit call_options: nil, &block
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.commit commit_options: commit_options do |c|
+        #     c.update "users", [{ id: 1, name: "Charlie", active: false }]
+        #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def commit commit_options: nil, call_options: nil, &block
           raise ArgumentError, "Must provide a block" unless block_given?
 
           @pool.with_session do |session|
-            session.commit(call_options: call_options, &block)
+            session.commit(
+              commit_options: commit_options, call_options: call_options, &block
+            )
           end
         end
 
         # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/BlockLength
         # rubocop:disable Metrics/MethodLength
 
         ##
@@ -1119,6 +1267,14 @@ module Google
         #
         # @param [Numeric] deadline The total amount of time in seconds the
         #   transaction has to succeed. The default is `120`.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
         # @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:
@@ -1137,7 +1293,8 @@ module Google
         # @yieldparam [Google::Cloud::Spanner::Transaction] transaction The
         #   Transaction object.
         #
-        # @return [Time] The timestamp at which the transaction committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -1173,7 +1330,28 @@ module Google
         #     end
         #   end
         #
-        def transaction deadline: 120, call_options: nil
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.transaction commit_options: commit_options do |tx|
+        #     results = tx.execute_query "SELECT * FROM users"
+        #
+        #     results.rows.each do |row|
+        #       puts "User #{row[:id]} is #{row[:name]}"
+        #     end
+        #
+        #     tx.update "users", [{ id: 1, name: "Charlie", active: false }]
+        #     tx.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def transaction deadline: 120, commit_options: nil, call_options: nil
           ensure_service!
           unless Thread.current[:transaction_id].nil?
             raise "Nested transactions are not allowed"
@@ -1189,8 +1367,11 @@ module Google
               yield tx
               commit_resp = @project.service.commit \
                 tx.session.path, tx.mutations,
-                transaction_id: tx.transaction_id, call_options: call_options
-              return Convert.timestamp_to_time commit_resp.commit_timestamp
+                transaction_id: tx.transaction_id,
+                commit_options: commit_options,
+                call_options: call_options
+              resp = CommitResponse.from_grpc commit_resp
+              commit_options ? resp : resp.timestamp
             rescue GRPC::Aborted, Google::Cloud::AbortedError => err
               # Re-raise if deadline has passed
               if current_time - start_time > deadline
@@ -1218,6 +1399,7 @@ module Google
         end
 
         # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/BlockLength
         # rubocop:enable Metrics/MethodLength
 
         ##

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

@@ -0,0 +1,87 @@
+# Copyright 2020 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/commit_response/commit_stats"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # CommitResponse is a timestamp at which the transaction committed
+      # with additional attributes of commit stats.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #
+      #   db = spanner.client "my-instance", "my-database"
+      #
+      #   timestamp = db.commit do |c|
+      #     c.update "users", [{ id: 1, name: "Charlie", active: false }]
+      #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+      #   end
+      #
+      #   puts timestamp
+      #
+      # @example With commit stats.
+      #   require "google/cloud/spanner"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #
+      #   db = spanner.client "my-instance", "my-database"
+      #
+      #   commit_options = { return_commit_stats: true }
+      #   commit_resp = db.commit commit_options: commit_options do |c|
+      #     c.update "users", [{ id: 1, name: "Charlie", active: false }]
+      #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+      #   end
+      #
+      #   puts commit_resp.timestamp
+      #   puts commit_resp.stats.mutation_count
+      #
+      class CommitResponse
+        ##
+        # @private Creates a new CommitResponse instance.
+        def initialize grpc
+          @grpc = grpc
+        end
+
+        ##
+        # The timestamp at which the transaction committed.
+        # @return [Time]
+        def timestamp
+          Convert.timestamp_to_time @grpc.commit_timestamp
+        end
+
+        ##
+        # Additional statistics about a commit.
+        # @return [CommitStats, nil] Commit stats or nil if not stats not
+        #   present.
+        def stats
+          CommitStats.from_grpc @grpc.commit_stats if @grpc.commit_stats
+        end
+
+        ##
+        # @private
+        # Creates a new Commit responsee instance from a
+        # `Google::Cloud::Spanner::V1::CommitResponse`.
+        def self.from_grpc grpc
+          new grpc
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/spanner/commit_response/commit_stats.rb

@@ -0,0 +1,51 @@
+# Copyright 2020 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/convert"
+
+module Google
+  module Cloud
+    module Spanner
+      class CommitResponse
+        ##
+        # # CommitStats
+        #
+        # Statistical information of a transaction commit.
+        #
+        class CommitStats
+          ##
+          # @private Creates a new CommitStats instance.
+          def initialize grpc
+            @grpc = grpc
+          end
+
+          # The total number of the mutations for the transaction.
+          # @return [Integer]
+          def mutation_count
+            @grpc.mutation_count
+          end
+
+          ##
+          # @private
+          # Creates a new CommitStats instance from a
+          # `Google::Cloud::Spanner::V1::CommitResponse::CommitStats`.
+          def self.from_grpc grpc
+            new grpc
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -397,7 +397,7 @@ module Google
         end
 
         def commit session_name, mutations = [], transaction_id: nil,
-                   call_options: nil
+                   commit_options: nil, call_options: nil
           tx_opts = nil
           if transaction_id.nil?
             tx_opts = V1::TransactionOptions.new(
@@ -410,6 +410,11 @@ module Google
             session: session_name, transaction_id: transaction_id,
             single_use_transaction: tx_opts, mutations: mutations
           }
+
+          if commit_options
+            request[:return_commit_stats] = commit_options[:return_commit_stats]
+          end
+
           service.commit request, opts
         end
 

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

@@ -16,6 +16,7 @@
 require "google/cloud/spanner/data"
 require "google/cloud/spanner/results"
 require "google/cloud/spanner/commit"
+require "google/cloud/spanner/commit_response"
 require "google/cloud/spanner/batch_update"
 
 module Google
@@ -484,6 +485,15 @@ module Google
         # @param [String] transaction_id The identifier of previously-started
         #   transaction to be used instead of starting a new transaction.
         #   Optional.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # transaction. Default it is `false`.
         # @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:
@@ -501,7 +511,8 @@ module Google
         # @yield [commit] The block for mutating the data.
         # @yieldparam [Google::Cloud::Spanner::Commit] commit The Commit object.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -515,15 +526,33 @@ module Google
         #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
         #   end
         #
-        def commit transaction_id: nil, call_options: nil
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.commit commit_options: commit_options do |c|
+        #     c.update "users", [{ id: 1, name: "Charlie", active: false }]
+        #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def commit transaction_id: nil, commit_options: nil, call_options: nil
           ensure_service!
           commit = Commit.new
           yield commit
           commit_resp = service.commit path, commit.mutations,
                                        transaction_id: transaction_id,
+                                       commit_options: commit_options,
                                        call_options: call_options
           @last_updated_at = Time.now
-          Convert.timestamp_to_time commit_resp.commit_timestamp
+          resp = CommitResponse.from_grpc commit_resp
+          commit_options ? resp : resp.timestamp
         end
 
         ##
@@ -552,6 +581,15 @@ module Google
         #
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
         # @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:
@@ -566,7 +604,8 @@ module Google
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -578,8 +617,28 @@ module Google
         #   db.upsert "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def upsert table, *rows, transaction_id: nil, call_options: nil
-          opts = { transaction_id: transaction_id, call_options: call_options }
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #             { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.upsert "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def upsert table, *rows, transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
           commit opts do |c|
             c.upsert table, rows
           end
@@ -611,6 +670,15 @@ module Google
         #
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
         # @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:
@@ -625,7 +693,8 @@ module Google
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -637,8 +706,28 @@ module Google
         #   db.insert "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def insert table, *rows, transaction_id: nil, call_options: nil
-          opts = { transaction_id: transaction_id, call_options: call_options }
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.insert "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def insert table, *rows, transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
           commit opts do |c|
             c.insert table, rows
           end
@@ -669,6 +758,15 @@ module Google
         #
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
         # @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:
@@ -683,7 +781,8 @@ module Google
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -695,8 +794,28 @@ module Google
         #   db.update "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def update table, *rows, transaction_id: nil, call_options: nil
-          opts = { transaction_id: transaction_id, call_options: call_options }
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true  }
+        #   commit_resp = db.update "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def update table, *rows, transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
           commit opts do |c|
             c.update table, rows
           end
@@ -729,6 +848,15 @@ module Google
         #
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`.
+        #
         # @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:
@@ -743,7 +871,8 @@ module Google
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -755,8 +884,28 @@ module Google
         #   db.replace "users", [{ id: 1, name: "Charlie", active: false },
         #                        { id: 2, name: "Harvey",  active: true }]
         #
-        def replace table, *rows, transaction_id: nil, call_options: nil
-          opts = { transaction_id: transaction_id, call_options: call_options }
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true  }
+        #   commit_resp = db.replace "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def replace table, *rows, transaction_id: nil, commit_options: nil,
+                    call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
           commit opts do |c|
             c.replace table, rows
           end
@@ -771,6 +920,14 @@ 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 [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
         # @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:
@@ -785,7 +942,8 @@ module Google
         #     * `:retry_codes` (`Array<String>`) - The error codes that should
         #       trigger a retry.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -796,8 +954,26 @@ module Google
         #
         #   db.delete "users", [1, 2, 3]
         #
-        def delete table, keys = [], transaction_id: nil, call_options: nil
-          opts = { transaction_id: transaction_id, call_options: call_options }
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.delete "users", [1,2,3], commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def delete table, keys = [], transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
           commit opts do |c|
             c.delete table, keys
           end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.2.0".freeze
+      VERSION = "2.3.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.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-15 00:00:00.000000000 Z
+date: 2021-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -282,6 +282,8 @@ files:
 - lib/google/cloud/spanner/client.rb
 - lib/google/cloud/spanner/column_value.rb
 - lib/google/cloud/spanner/commit.rb
+- lib/google/cloud/spanner/commit_response.rb
+- lib/google/cloud/spanner/commit_response/commit_stats.rb
 - lib/google/cloud/spanner/convert.rb
 - lib/google/cloud/spanner/credentials.rb
 - lib/google/cloud/spanner/data.rb
@@ -329,7 +331,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.6
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Spanner API