google-cloud-spanner 2.37.0 → 2.37.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '076293b0ad0c908dfa858b6a370dd3ad88d99f26739c85f72292c41329991228'
-  data.tar.gz: 499e83b90c725a4c84058708e4af53e1db4839f312c263b2f41b8e27b233cce0
+  metadata.gz: 85dbbe5aa02ac93080c438688ca3f120a8435c8816fcd17ce64660e3b6bbc7ae
+  data.tar.gz: 741c37bb89f744d42fbd0d081511de90e069c999b6978f66482cca282d154200
 SHA512:
-  metadata.gz: 6b4ffb38b9c48441e24490158a37932846f3befcd6633db3fde64c4ab036f472367bcf62817a0118d783ee981216a7ba5343dab51b1e0e2bb48332d796903817
-  data.tar.gz: b41377cf7cb39c851ba30dfd259413c78c62c1341eb539b73ef1376286d93bb010ffa85def0cc7b99522d01589b5cb2ea0290174f53c285f69cc4366140337bb
+  metadata.gz: 49ef3061971e4673bac749c9fe8515db3d59c055261139113d432491a402093f37c27c9e92ed9dfedd85a9b5440b0f84538aa76b9e56fb41c10fb9eab0a05f33
+  data.tar.gz: 17d0238b2433dda6e57732d4a081fb1556b68ed2422b7f15cbedd48ca1ebd46705209eca4f28f9af61541a68ea846676e658e9566d11e95b57705e7f4670f7a8

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.37.0".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.37.0
+  version: 2.37.1
 platform: ruby
 authors:
 - Mike Moore