Purge Queue

Overview

Purging a queue is a management-plane operation for wiping a channel's backlog without receiving and discarding messages one at a time. Reach for it when a bad producer floods a channel, when you need a clean slate between test runs, or when you're resetting a queue during a maintenance window — all without deleting and recreating the channel itself.

purge_queue_channel tells the broker directly to acknowledge and drop every message still pending on the specified channel, entirely server-side. Pairing it with a peek: true receive lets you confirm the queue is empty afterward without consuming anything.

Gotchas: the purge is irreversible — there's no undo once messages are dropped. It only reaches messages still waiting in the queue; anything already delivered to and held by an active consumer is untouched, so a purge run right after a receive can still leave stragglers. And purging empties the channel, it doesn't delete it — new messages can be sent immediately afterward.

Prerequisites

• KubeMQ server running on localhost:50000
• Ruby SDK installed (gem install kubemq)

Code

require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')
channel = 'ruby-management.purge-queue'

begin
  client = KubeMQ::QueuesClient.new(address: address, client_id: 'mgmt-purge-example')
  puts "Connected to #{address}"

  5.times do |i|
    msg = KubeMQ::Queues::QueueMessage.new(channel: channel, metadata: "item-#{i}", body: "data-#{i}")
    client.send_queue_message(msg)
  end
  puts "Sent 5 messages to #{channel}"

  before = client.receive_queue_messages(channel: channel, max_messages: 10, wait_timeout_seconds: 2, peek: true)
  puts "Before purge: #{before.size} messages"

  client.purge_queue_channel(channel_name: channel)
  puts 'Queue purged'

  after = client.receive_queue_messages(channel: channel, max_messages: 10, wait_timeout_seconds: 2, peek: true)
  puts "After purge: #{after.size} messages"
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  client&.close
  puts 'Done'
end

How It Works

• purge_queue_channel removes all messages from the specified queue channel.
• Use peek: true to verify the queue is empty without consuming messages.
• Purge is irreversible — all messages are permanently deleted.
• Review timeouts, channel names, and client IDs before running against shared environments.

Related

• Ruby SDK Reference
• Send & Receive