google-cloud-spanner 2.36.1 → 2.37.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dacf40c7c666295fd6990ae06f0c07544bcca11062b61db5e6c4e18a4bb40b1c
-  data.tar.gz: 25cc74325e202f801b83204fad1630bf49c7af00e86d88948a17938882d93f25
+  metadata.gz: 85dbbe5aa02ac93080c438688ca3f120a8435c8816fcd17ce64660e3b6bbc7ae
+  data.tar.gz: 741c37bb89f744d42fbd0d081511de90e069c999b6978f66482cca282d154200
 SHA512:
-  metadata.gz: d2e5587393eaeace0f6446eea28444bc9dce49f9ffecde69d4dae377b77fd5ad43709d7f0e1b18e1202fcbda448af26c4d22cc6517876ffdb47ffa9d747bbf2b
-  data.tar.gz: 354a92c99c6c1736c72c5172407ab9ce23d80ddd8be08bee45e26500c92e6aab7e81599ec6c1087533a40d2f77a64e0c8488a0441f9ae4f61a2380b0fc08ee85
+  metadata.gz: 49ef3061971e4673bac749c9fe8515db3d59c055261139113d432491a402093f37c27c9e92ed9dfedd85a9b5440b0f84538aa76b9e56fb41c10fb9eab0a05f33
+  data.tar.gz: 17d0238b2433dda6e57732d4a081fb1556b68ed2422b7f15cbedd48ca1ebd46705209eca4f28f9af61541a68ea846676e658e9566d11e95b57705e7f4670f7a8

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Release History
 
+### 2.37.1 (2026-11-02)
+
+#### Documentation
+
+* document queues in OVERVIEW.md and Client ([#265](https://github.com/googleapis/ruby-spanner/issues/265)) 
+
+### 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/OVERVIEW.md

@@ -298,6 +298,77 @@ db.snapshot do |snp|
 end
 ```
 
+## Using queues
+
+A queue holds messages for consumers to receive. You create queues with the
+`CREATE QUEUE` statement (see the [DDL
+reference](https://cloud.google.com/spanner/docs/reference/standard-sql/data-definition-language)).
+The examples in this section use this queue:
+
+```sql
+CREATE QUEUE OrderQueue (
+  Id INT64 NOT NULL,
+  Payload STRING(MAX) NOT NULL
+) PRIMARY KEY (Id)
+```
+
+Use {Google::Cloud::Spanner::Commit#send_message Commit#send_message} to send a
+message. The payload is converted the same way as column values, so pass a
+`String` for a `STRING` payload column:
+
+```ruby
+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"
+end
+```
+
+If a queue's payload column is `BYTES`, wrap the binary data in a `StringIO`,
+as you would for a `BYTES` column in a table:
+
+```ruby
+db.commit do |c|
+  c.send_message "LabelQueue", 101, StringIO.new(File.binread("label.png"))
+end
+```
+
+Receive messages with the `RECEIVE_<queue>` table-valued function, and use
+{Google::Cloud::Spanner::Transaction#ack_message Transaction#ack_message} to
+acknowledge each one in the same transaction as the write it caused:
+
+```ruby
+require "google/cloud/spanner"
+
+spanner = Google::Cloud::Spanner.new
+
+db = spanner.client "my-instance", "my-database"
+
+results = db.execute_query "SELECT Id, Payload FROM RECEIVE_OrderQueue()"
+
+results.rows.each do |row|
+  db.transaction do |tx|
+    tx.update "orders", [{ id: row[:Id], status: "PROCESSED" }]
+    tx.ack_message "OrderQueue", row[:Id]
+  end
+end
+```
+
+To delay delivery, pass `deliver_time:`. To ack a message that might not
+exist, pass `ignore_not_found: true`:
+
+```ruby
+db.commit do |c|
+  c.send_message "OrderQueue", 102, "Order payload",
+                 deliver_time: Time.now + 300
+  c.ack_message "OrderQueue", 101, ignore_not_found: true
+end
+```
+
 ## Deleting databases
 
 Use {Google::Cloud::Spanner::Admin::Database#database_admin

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

@@ -35,6 +35,12 @@ module Google
       #
       # A client is used to read and/or modify data in a Cloud Spanner database.
       #
+      # A client also works with queues. Send and acknowledge messages with
+      # {Commit#send_message} and {Commit#ack_message} inside {#commit}, or with
+      # {Transaction#send_message} and {Transaction#ack_message} inside
+      # {#transaction}. Receive messages by querying the queue's `RECEIVE_`
+      # function with {#execute_query}.
+      #
       # See {Google::Cloud::Spanner::Project#client}.
       #
       # @example
@@ -506,6 +512,20 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
+        # @example Receive messages from a queue with the RECEIVE_ function:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   # RECEIVE_ needs a strong read, which is the default here.
+        #   results = db.execute_query "SELECT Id, Payload FROM RECEIVE_OrderQueue()"
+        #
+        #   results.rows.each do |row|
+        #     puts "Received message #{row[:Id]}"
+        #   end
+        #
         def execute_query sql, params: nil, types: nil, single_use: nil,
                           query_options: nil, request_options: nil,
                           call_options: nil, directed_read_options: nil

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.1".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.1
 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: