feat(spanner): add send_message and ack_message for queues

acceptance/data/fixtures.rb

@@ -196,6 +196,17 @@ def items_ddl_statement
       ITEMS
     end
 
+    # Not part of schema_ddl_statements: queues need an Enterprise edition
+    # instance, and the emulator doesn't support them yet.
+    def queue_ddl_statement
+      <<~QUEUE
+        CREATE QUEUE IF NOT EXISTS TestQueue (
+        Id INT64 NOT NULL,
+        Payload BYTES(MAX) NOT NULL
+        ) PRIMARY KEY (Id)
+      QUEUE
+    end
+
     def schema_pg_ddl_statements
       [
         stuff_pg_ddl_statement,

google-cloud-spanner/OVERVIEW.md

@@ -298,6 +298,60 @@ 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)).
+
+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 wrap binary
+data in a `StringIO`, as you would for a `BYTES` 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, StringIO.new("Order payload")
+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
+```
+
+Optional settings go in a {Google::Cloud::Spanner::SendOptions SendOptions} or
+{Google::Cloud::Spanner::AckOptions AckOptions}, or in a hash with the same
+keys:
+
+```ruby
+db.commit do |c|
+  c.send_message "OrderQueue", 102, StringIO.new("Order payload"),
+                 send_options: { deliver_time: Time.now + 300 }
+end
+```
+
 ## Deleting databases
 
 Use {Google::Cloud::Spanner::Admin::Database#database_admin

google-cloud-spanner/acceptance/spanner/client/queues_test.rb

@@ -0,0 +1,59 @@
+# Copyright 2026 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 "spanner_helper"
+
+# An ack without ignore_not_found fails with NOT_FOUND unless the message
+# exists, so a successful ack also shows that the send landed.
+describe "Spanner Client Queues", :queues, :spanner do
+  let(:db) { spanner_client }
+
+  before do
+    skip "Cloud Spanner Emulator does not yet support Queues (Send & Ack)" if emulator_enabled?
+
+    # Created once per run, in the per-run test database.
+    $spanner_test_queue_created ||= begin
+      db_job = db.database.update statements: [queue_ddl_statement]
+      db_job.wait_until_done!
+      raise GRPC::BadStatus.new(db_job.error.code, db_job.error.message) if db_job.error?
+      true
+    end
+  end
+
+  it "sends and acks messages with Client#commit" do
+    commit_time = db.commit do |c|
+      c.send_message "TestQueue", 1, StringIO.new("payload1")
+      c.send_message "TestQueue", 2, StringIO.new("payload2")
+    end
+    _(commit_time).must_be_kind_of Time
+
+    commit_time = db.commit do |c|
+      c.ack_message "TestQueue", 1
+      c.ack_message "TestQueue", 2
+    end
+    _(commit_time).must_be_kind_of Time
+  end
+
+  it "sends and acks a message with Client#transaction" do
+    commit_time = db.transaction do |tx|
+      tx.send_message "TestQueue", 3, StringIO.new("payload3")
+    end
+    _(commit_time).must_be_kind_of Time
+
+    commit_time = db.transaction do |tx|
+      tx.ack_message "TestQueue", 3
+    end
+    _(commit_time).must_be_kind_of Time
+  end
+end

google-cloud-spanner/google-cloud-spanner.gemspec

@@ -24,5 +24,5 @@ Gem::Specification.new do |gem|
   gem.add_dependency "google-cloud-core", "~> 1.7"
   gem.add_dependency "google-cloud-spanner-admin-database-v1", "~> 1.4"
   gem.add_dependency "google-cloud-spanner-admin-instance-v1", "~> 1.6"
-  gem.add_dependency "google-cloud-spanner-v1", "~> 1.6"
+  gem.add_dependency "google-cloud-spanner-v1", "~> 1.12"
 end

google-cloud-spanner/lib/google/cloud/spanner/ack_options.rb

@@ -0,0 +1,60 @@
+# Copyright 2026 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.
+
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # AckOptions
+      #
+      # Optional settings for acknowledging a queue message with
+      # {Commit#ack_message} or {Transaction#ack_message}. A hash with the
+      # same keys can be passed instead.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #
+      #   db = spanner.client "my-instance", "my-database"
+      #
+      #   ack_options = Google::Cloud::Spanner::AckOptions.new ignore_not_found: true
+      #
+      #   db.commit do |c|
+      #     c.ack_message "OrderQueue", 101, ack_options: ack_options
+      #   end
+      #
+      class AckOptions
+        ##
+        # Whether the ack succeeds when the message doesn't exist.
+        #
+        # @return [Boolean]
+        attr_reader :ignore_not_found
+
+        ##
+        # Creates a new AckOptions.
+        #
+        # @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.
+        #
+        def initialize ignore_not_found: false
+          @ignore_not_found = ignore_not_found
+        end
+      end
+    end
+  end
+end

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

@@ -35,6 +35,12 @@ module Spanner
       #
       # 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 @@ def directed_read_options
         #     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