google-cloud-spanner 2.22.0 → 2.24.0

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

@@ -25,6 +25,7 @@ require "google/cloud/spanner/column_value"
 require "google/cloud/spanner/convert"
 require "google/cloud/spanner/commit_response"
 require "google/cloud/spanner/lar_headers"
+require "google/cloud/spanner/batch_write_results"
 
 module Google
   module Cloud
@@ -624,6 +625,9 @@ module Google
         #     `[:INT64]`.
         #   * {Fields} - Nested Structs are specified by providing a Fields
         #     object.
+        # @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] query_options A hash of values to specify the custom
         #   query options for executing SQL query. Query options are optional.
         #   The following settings can be provided:
@@ -735,6 +739,7 @@ module Google
         #     request_options: request_options
         #
         def execute_partition_update sql, params: nil, types: nil,
+                                     exclude_txn_from_change_streams: false,
                                      query_options: nil, request_options: nil,
                                      call_options: nil
           ensure_service!
@@ -745,9 +750,10 @@ module Google
           route_to_leader = LARHeaders.partition_query
           results = nil
           @pool.with_session do |session|
+            transaction = pdml_transaction session, exclude_txn_from_change_streams: exclude_txn_from_change_streams
             results = session.execute_query \
               sql, params: params, types: types,
-              transaction: pdml_transaction(session),
+              transaction: transaction,
               query_options: query_options, request_options: request_options,
               call_options: call_options, route_to_leader: route_to_leader
           end
@@ -1020,6 +1026,9 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @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] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1042,6 +1051,20 @@ module Google
         #   * `:tag` (String) A tag used for statistics collection
         #     about transaction. A tag must be a valid identifier of the format:
         #     `[a-zA-Z][a-zA-Z0-9_\-]{0,49}`.
+        # @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.
+        #
         #
         # @return [Time, CommitResponse] The timestamp at which the operation
         #   committed. If commit options are set it returns {CommitResponse}.
@@ -1095,13 +1118,18 @@ module Google
         #                       { id: 2, name: "Harvey",  active: true }],
         #                       request_options: request_options
         #
-        def upsert table, rows, commit_options: nil, request_options: nil
+        def upsert table, rows,
+                   exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
-            session.upsert table, rows, commit_options: commit_options,
-                           request_options: request_options
+            session.upsert table, rows,
+                           exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           commit_options: commit_options,
+                           request_options: request_options,
+                           call_options: call_options
           end
         end
         alias save upsert
@@ -1144,6 +1172,9 @@ module Google
         #
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        # @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] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1166,6 +1197,20 @@ module Google
         #   * `:tag` (String) A tag used for statistics collection
         #     about transaction. A tag must be a valid identifier of the
         #     format: `[a-zA-Z][a-zA-Z0-9_\-]{0,49}`.
+        # @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.
+        #
         #
         # @return [Time, CommitResponse] The timestamp at which the operation
         #   committed. If commit options are set it returns {CommitResponse}.
@@ -1219,13 +1264,18 @@ module Google
         #                       { id: 2, name: "Harvey",  active: true }],
         #                       request_options: request_options
         #
-        def insert table, rows, commit_options: nil, request_options: nil
+        def insert table, rows,
+                   exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
-            session.insert table, rows, commit_options: commit_options,
-                           request_options: request_options
+            session.insert table, rows,
+                           exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           commit_options: commit_options,
+                           request_options: request_options,
+                           call_options: call_options
           end
         end
 
@@ -1267,6 +1317,9 @@ module Google
         #
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        # @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] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1289,6 +1342,20 @@ module Google
         #   * `:tag` (String) A tag used for statistics collection
         #     about transaction. A tag must be a valid identifier of the
         #     format: `[a-zA-Z][a-zA-Z0-9_\-]{0,49}`.
+        # @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.
+        #
         #
         # @return [Time, CommitResponse] The timestamp at which the operation
         #   committed. If commit options are set it returns {CommitResponse}.
@@ -1341,13 +1408,18 @@ module Google
         #                       { id: 2, name: "Harvey",  active: true }],
         #                      request_options: request_options
         #
-        def update table, rows, commit_options: nil, request_options: nil
+        def update table, rows,
+                   exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
-            session.update table, rows, commit_options: commit_options,
-                           request_options: request_options
+            session.update table, rows,
+                           exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           commit_options: commit_options,
+                           request_options: request_options,
+                           call_options: call_options
           end
         end
 
@@ -1391,6 +1463,9 @@ module Google
         #
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        # @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] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1413,6 +1488,20 @@ module Google
         #   * `:tag` (String) A tag used for statistics collection
         #     about transaction. A tag must be a valid identifier of the
         #     format: `[a-zA-Z][a-zA-Z0-9_\-]{0,49}`.
+        # @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.
+        #
         #
         # @return [Time, CommitResponse] The timestamp at which the operation
         #   committed. If commit options are set it returns {CommitResponse}.
@@ -1465,10 +1554,15 @@ module Google
         #                        { id: 2, name: "Harvey",  active: true }],
         #                       request_options: request_options
         #
-        def replace table, rows, commit_options: nil, request_options: nil
+        def replace table, rows,
+                    exclude_txn_from_change_streams: false,
+                    commit_options: nil, request_options: nil, call_options: nil
           @pool.with_session do |session|
-            session.replace table, rows, commit_options: commit_options,
-                            request_options: request_options
+            session.replace table, rows,
+                            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                            commit_options: commit_options,
+                            request_options: request_options,
+                            call_options: call_options
           end
         end
 
@@ -1492,6 +1586,9 @@ 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 [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] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1573,13 +1670,16 @@ module Google
         #   request_options = { tag: "BulkDelete-Users" }
         #   db.delete "users", [1, 2, 3], request_options: request_options
         #
-        def delete table, keys = [], commit_options: nil, request_options: nil,
-                   call_options: nil
+        def delete table, keys = [],
+                   exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           request_options = Convert.to_request_options \
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
-            session.delete table, keys, commit_options: commit_options,
+            session.delete table, keys,
+                           exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                           commit_options: commit_options,
                            request_options: request_options,
                            call_options: call_options
           end
@@ -1600,6 +1700,9 @@ module Google
         # this method may be appropriate for latency sensitive and/or high
         # throughput blind changes.
         #
+        # @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] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1695,8 +1798,9 @@ module Google
         #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
         #   end
         #
-        def commit commit_options: nil, request_options: nil,
-                   call_options: nil, &block
+        def commit exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil,
+                   &block
           raise ArgumentError, "Must provide a block" unless block_given?
 
           request_options = Convert.to_request_options \
@@ -1704,12 +1808,111 @@ module Google
 
           @pool.with_session do |session|
             session.commit(
+              exclude_txn_from_change_streams: exclude_txn_from_change_streams,
               commit_options: commit_options, request_options: request_options,
               call_options: call_options, &block
             )
           end
         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,
+                        &block
+          raise ArgumentError, "Must provide a block" unless block_given?
+
+          @pool.with_session do |session|
+            session.batch_write(
+              exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+              request_options: request_options,
+              call_options: call_options,
+              &block
+            )
+          end
+        end
+
         # rubocop:disable Metrics/AbcSize
         # rubocop:disable Metrics/MethodLength
         # rubocop:disable Metrics/BlockLength
@@ -1731,6 +1934,9 @@ module Google
         #
         # @param [Numeric] deadline The total amount of time in seconds the
         #   transaction has to succeed. The default is `120`.
+        # @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] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1870,8 +2076,8 @@ module Google
         #     tx.insert "users", [{ id: 2, name: "Harvey",  active: true }]
         #   end
         #
-        def transaction deadline: 120, commit_options: nil,
-                        request_options: nil, call_options: nil
+        def transaction deadline: 120, exclude_txn_from_change_streams: false,
+                        commit_options: nil, request_options: nil, call_options: nil
           ensure_service!
           unless Thread.current[IS_TRANSACTION_RUNNING_KEY].nil?
             raise "Nested transactions are not allowed"
@@ -1885,7 +2091,7 @@ module Google
             request_options, tag_type: :transaction_tag
 
           @pool.with_session do |session|
-            tx = session.create_empty_transaction
+            tx = session.create_empty_transaction exclude_txn_from_change_streams: exclude_txn_from_change_streams
             if request_options
               tx.transaction_tag = request_options[:transaction_tag]
             end
@@ -1898,6 +2104,7 @@ module Google
               commit_resp = @project.service.commit \
                 tx.session.path, tx.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
@@ -1911,7 +2118,7 @@ module Google
               # Sleep the amount from RetryDelay, or incremental backoff
               sleep(delay_from_aborted(e) || backoff *= 1.3)
               # Create new transaction on the session and retry the block
-              tx = session.create_transaction
+              tx = session.create_transaction exclude_txn_from_change_streams: exclude_txn_from_change_streams
               retry
             rescue StandardError => e
               # Rollback transaction when handling unexpected error
@@ -2306,8 +2513,9 @@ module Google
               }.compact)))
         end
 
-        def pdml_transaction session
-          pdml_tx_grpc = @project.service.create_pdml session.path
+        def pdml_transaction session, exclude_txn_from_change_streams: false
+          pdml_tx_grpc = @project.service.create_pdml session.path,
+                                                      exclude_txn_from_change_streams: exclude_txn_from_change_streams
           V1::TransactionSelector.new id: pdml_tx_grpc.id
         end
 

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

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

data/lib/google/cloud/spanner/database/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_database}
-        # instead.
+        #   {Google::Cloud::Spanner::Admin::Database.database_admin}.create_database instead.
         #
         # @example
         #   require "google/cloud/spanner"

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

@@ -26,9 +26,8 @@ module Google
         # Database::List is a special case Array with additional
         # values.
         #
-        # @deprecated Use the result of
-        # {Google::Cloud::Spanner::Admin::Database#database_admin Client#list_databases}
-        # instead.
+        # @deprecated Use the result of {Google::Cloud::Spanner::Admin::Database.database_admin}.list_databases
+        #   instead.
         class List < DelegateClass(::Array)
           ##
           # If not empty, indicates that there are more records that match

data/lib/google/cloud/spanner/instance/config/list.rb

@@ -27,9 +27,8 @@ module Google
           # Instance::Config::List is a special case Array with additional
           # values.
           #
-          # @deprecated Use the result of
-          # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#list_instance_configs}
-          # instead.
+          # @deprecated Use the result of the
+          #   {Google::Cloud::Spanner::Admin::Instance.instance_admin}.list_instance_configs instead.
           class List < DelegateClass(::Array)
             ##
             # If not empty, indicates that there are more records that match

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

@@ -34,9 +34,8 @@ module Google
         # @see https://cloud.google.com/spanner/reference/rpc/google.longrunning#google.longrunning.Operation
         #   Long-running Operation
         #
-        # @deprecated Use the long-running operation returned by
-        # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#create_instance}
-        # instead.
+        # @deprecated Use the long-running operation returned by the
+        #   {Google::Cloud::Spanner::Admin::Instance.instance_admin}.create_instance instead.
         #
         # @example
         #   require "google/cloud/spanner"

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

@@ -26,9 +26,8 @@ module Google
         # Instance::List is a special case Array with additional
         # values.
         #
-        # @deprecated Use the result of
-        # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#list_instances}
-        # instead.
+        # @deprecated Use the result of {Google::Cloud::Spanner::Admin::Instance.instance_admin}.list_instances
+        #   instead.
         class List < DelegateClass(::Array)
           ##
           # If not empty, indicates that there are more records that match

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

@@ -258,12 +258,13 @@ module Google
           ensure_service!
 
           field_mask = []
-          @current_values.each do |field, value|
-            field_mask << field unless @grpc[field.to_s] == value
+          new_values = @grpc.to_h
+          (@current_values.keys + new_values.keys).uniq.each do |field|
+            field_mask << field unless new_values[field] == @current_values[field]
           end
 
           job_grpc = service.update_instance @grpc, field_mask: field_mask
-          @current_values = @grpc.to_h
+          @current_values = new_values
           Instance::Job.from_grpc job_grpc, service
         end
         alias update save

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

@@ -60,6 +60,10 @@ module Google
             "true"
           end
 
+          def batch_write
+            "true"
+          end
+
           def execute_batch_dml
             "true"
           end