google-cloud-spanner 2.36.1 → 2.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dacf40c7c666295fd6990ae06f0c07544bcca11062b61db5e6c4e18a4bb40b1c
-  data.tar.gz: 25cc74325e202f801b83204fad1630bf49c7af00e86d88948a17938882d93f25
+  metadata.gz: '076293b0ad0c908dfa858b6a370dd3ad88d99f26739c85f72292c41329991228'
+  data.tar.gz: 499e83b90c725a4c84058708e4af53e1db4839f312c263b2f41b8e27b233cce0
 SHA512:
-  metadata.gz: d2e5587393eaeace0f6446eea28444bc9dce49f9ffecde69d4dae377b77fd5ad43709d7f0e1b18e1202fcbda448af26c4d22cc6517876ffdb47ffa9d747bbf2b
-  data.tar.gz: 354a92c99c6c1736c72c5172407ab9ce23d80ddd8be08bee45e26500c92e6aab7e81599ec6c1087533a40d2f77a64e0c8488a0441f9ae4f61a2380b0fc08ee85
+  metadata.gz: 6b4ffb38b9c48441e24490158a37932846f3befcd6633db3fde64c4ab036f472367bcf62817a0118d783ee981216a7ba5343dab51b1e0e2bb48332d796903817
+  data.tar.gz: b41377cf7cb39c851ba30dfd259413c78c62c1341eb539b73ef1376286d93bb010ffa85def0cc7b99522d01589b5cb2ea0290174f53c285f69cc4366140337bb

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### 2.37.0 (2026-10-28)
+
+#### Features
+
+* add send_message and ack_message to Commit ([#262](https://github.com/googleapis/ruby-spanner/issues/262)) 
+* add send_message and ack_message to Transaction ([#263](https://github.com/googleapis/ruby-spanner/issues/263)) 
+#### Documentation
+
+* link to the published Ruby version support policy ([#272](https://github.com/googleapis/ruby-spanner/issues/272)) 
+
 ### 2.36.1 (2026-10-13)
 
 #### Documentation

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

@@ -280,6 +280,124 @@ module Google
           keys
         end
 
+        ##
+        # Sends a message to a queue.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#commit} completes.
+        #
+        # @param [String] queue The name of the queue.
+        # @param [Object, Array<Object>] key A single key or array of composite key parts for the message.
+        # @param [String, IO, StringIO, Hash, Google::Protobuf::MessageExts] payload
+        #   The message payload. It is converted the same way as column values
+        #   (see {#upsert}), so its type must match the queue's payload column,
+        #   such as a `String` for `STRING` or a `StringIO` for `BYTES`:
+        #   * `String` - Sent as text.
+        #   * `IO`, `StringIO`, `File` - Sent as bytes (Base64-encoded). Ruby has
+        #     no bytes type, so wrap binary data in a `StringIO`.
+        #   * `Hash` - Serialized to a JSON string.
+        #   * `Google::Protobuf::MessageExts` - Serialized and Base64-encoded.
+        # @param [Time, nil] deliver_time The time at which Spanner begins
+        #   trying to deliver the message. Optional. If not set, the message is
+        #   delivered immediately. A time in the past is replaced with a time
+        #   closer to the current time.
+        #
+        # @return [Object, Array<Object>] The key of the message.
+        #
+        # @raise [ArgumentError] If the payload type is unsupported.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   # OrderQueue has a STRING(MAX) payload column.
+        #   db.commit do |c|
+        #     c.send_message "OrderQueue", 101, "Order payload"
+        #   end
+        #
+        # @example Send binary data to a queue with a BYTES payload column
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.send_message "LabelQueue", 101, StringIO.new(File.binread("label.png"))
+        #   end
+        #
+        # @example Deliver the message in five minutes
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.send_message "OrderQueue", 101, "Order payload",
+        #                    deliver_time: Time.now + 300
+        #   end
+        #
+        def send_message queue, key, payload, deliver_time: nil
+          send_mutation = V1::Mutation::Send.new(
+            queue: queue,
+            key: key_list_value(key),
+            payload: Convert.object_to_grpc_value(payload),
+            deliver_time: Convert.time_to_timestamp(deliver_time)
+          )
+          @mutations += [V1::Mutation.new(send: send_mutation)]
+          key
+        end
+
+        ##
+        # Acknowledges a message in a queue, which removes it from the queue.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#commit} completes.
+        #
+        # @param [String] queue The name of the queue.
+        # @param [Object, Array<Object>] key A single key or array of composite key parts to match.
+        # @param [Boolean] ignore_not_found If `true`, the ack succeeds even if
+        #   the message doesn't exist. Optional. The default is `false`, which
+        #   fails the commit with `NOT_FOUND` when the message doesn't exist.
+        #
+        # @return [Object, Array<Object>] The key of the message.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.ack_message "OrderQueue", 101
+        #   end
+        #
+        # @example Ack a message whether or not it exists
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.ack_message "OrderQueue", 101, ignore_not_found: true
+        #   end
+        #
+        def ack_message queue, key, ignore_not_found: false
+          ack_mutation = V1::Mutation::Ack.new(
+            queue: queue,
+            key: key_list_value(key),
+            ignore_not_found: ignore_not_found
+          )
+          @mutations += [V1::Mutation.new(ack: ack_mutation)]
+          key
+        end
+
         # Return the current mutations added to this `Spanner::Commit` object.
         # @private
         # @return [Array<Google::Cloud::Spanner::V1::Mutation>]
@@ -325,6 +443,21 @@ module Google
           rows
         end
 
+        ##
+        # @private
+        # Generates a `ListValue` protobuf containing gRPC values for the given primary key.
+        #
+        # @param [Object, Array<Object>] key A scalar key, or an array of a composite key's parts.
+        # @return [Google::Protobuf::ListValue]
+        #
+        def key_list_value key
+          key = [key] unless key.is_a? Array
+          key_list = key.map do |k|
+            Convert.object_to_grpc_value k
+          end
+          Google::Protobuf::ListValue.new values: key_list
+        end
+
         def key_set keys
           return V1::KeySet.new all: true if keys.nil?
           keys = [keys] unless keys.is_a? Array

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

@@ -1075,6 +1075,79 @@ module Google
           @commit.delete table, keys
         end
 
+        ##
+        # Sends a message to a queue.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#transaction} completes.
+        #
+        # @param [String] queue The name of the queue.
+        # @param [Object, Array<Object>] key A single key or array of composite key parts for the message.
+        # @param [String, IO, StringIO, Hash, Google::Protobuf::MessageExts] payload
+        #   The message payload. It is converted the same way as column values
+        #   (see {#upsert}), so its type must match the queue's payload column,
+        #   such as a `String` for `STRING` or a `StringIO` for `BYTES`:
+        #   * `String` - Sent as text.
+        #   * `IO`, `StringIO`, `File` - Sent as bytes (Base64-encoded). Ruby has
+        #     no bytes type, so wrap binary data in a `StringIO`.
+        #   * `Hash` - Serialized to a JSON string.
+        #   * `Google::Protobuf::MessageExts` - Serialized and Base64-encoded.
+        # @param [Time, nil] deliver_time The time at which Spanner begins
+        #   trying to deliver the message. Optional. If not set, the message is
+        #   delivered immediately. A time in the past is replaced with a time
+        #   closer to the current time.
+        #
+        # @return [Object, Array<Object>] The key of the message.
+        #
+        # @raise [ArgumentError] If the payload type is unsupported.
+        #
+        # @example Send a message in the same transaction as the row it describes
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   # OrderQueue has a STRING(MAX) payload column.
+        #   db.transaction do |tx|
+        #     tx.insert "orders", [{ id: 101, status: "NEW" }]
+        #     tx.send_message "OrderQueue", 101, "Order payload"
+        #   end
+        #
+        def send_message queue, key, payload, deliver_time: nil
+          ensure_session!
+          @commit.send_message queue, key, payload, deliver_time: deliver_time
+        end
+
+        ##
+        # Acknowledges a message in a queue, which removes it from the queue.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#transaction} completes.
+        #
+        # @param [String] queue The name of the queue.
+        # @param [Object, Array<Object>] key A single key or array of composite key parts to match.
+        # @param [Boolean] ignore_not_found If `true`, the ack succeeds even if
+        #   the message doesn't exist. Optional. The default is `false`, which
+        #   fails the commit with `NOT_FOUND` when the message doesn't exist.
+        #
+        # @return [Object, Array<Object>] The key of the message.
+        #
+        # @example Ack a message in the same transaction as the write it caused
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     tx.update "orders", [{ id: 101, status: "PROCESSED" }]
+        #     tx.ack_message "OrderQueue", 101
+        #   end
+        #
+        def ack_message queue, key, ignore_not_found: false
+          ensure_session!
+          @commit.ack_message queue, key, ignore_not_found: ignore_not_found
+        end
+
         ##
         # @private
         # Returns the field names and types for a table.

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.36.1".freeze
+      VERSION = "2.37.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.36.1
+  version: 2.37.0
 platform: ruby
 authors:
 - Mike Moore
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.12'
 description: google-cloud-spanner is the official library for Google Cloud Spanner
   API.
 email: