Module: Valkey::Commands::PubSubCommands

Defined in:
lib/valkey/commands/pubsub_commands.rb

Overview

This module contains commands for Valkey Pub/Sub.

Pub/Sub requires the RESP3 protocol. Subscriptions can be declared when the client is created, and are applied via SUBSCRIBE/PSUBSCRIBE/SSUBSCRIBE during connection establishment:

valkey = Valkey.new(
protocol: :resp3,
pubsub: {
  subscriptions: {
    exact: ["news"],           # channel names
    pattern: ["news.*"],       # channel name patterns
    sharded: ["shard-chan"]    # sharded channels, cluster mode only
  }
}
)

There are three ways to receive messages:

  • Inline: messages are queued on the connection and read with #get_pubsub_message or #try_get_pubsub_message.
  • Callback: a callback: proc receives every message instead, along with an arbitrary context:. Not supported yet.
  • Lazy: the _lazy subscribe and unsubscribe methods return without waiting for the server to confirm the change; read back #get_subscriptions to see the subscriptions the server actually has.

Instance Method Summary collapse

Instance Method Details

#get_pubsub_message ⇒ Valkey::Glide::PubSub::Message?

Get the next Pub/Sub message, blocking until one is available.

Examples:

Consume messages until the client is closed

while (message = valkey.get_pubsub_message)
  handle(message.channel, message.message)
end

Returns:



306
307
308
# File 'lib/valkey/commands/pubsub_commands.rb', line 306

def get_pubsub_message
  @pubsub.get_message
end

#get_subscriptions ⇒ Valkey::Glide::PubSub::SubscriptionState

Get this connection's subscription state: what the client asked for and what the server confirmed.

Examples:

Compare desired and actual subscriptions

state = valkey.get_subscriptions
state.desired_subscriptions
  # => {exact: ["channel1"], pattern: ["news.*"], sharded: ["shard1"]}
state.actual_subscriptions
  # => {exact: ["channel1"], pattern: [], sharded: ["shard1"]}

Returns:

Raises:

  • (NotImplementedError) —

    this method is not implemented yet



337
338
339
# File 'lib/valkey/commands/pubsub_commands.rb', line 337

def get_subscriptions
  @pubsub.get_subscriptions
end

#psubscribe(*patterns, timeout: nil) ⇒ void

This method returns an undefined value.

Subscribe to channel patterns, waiting for the server to confirm the subscription.

Examples:

Subscribe to patterns

valkey.psubscribe("news.*", "events.*")

Give up if the server does not confirm within 1 second

valkey.psubscribe("news.*", timeout: 1)

Parameters:

  • patterns (Array<String>) —

    the glob-style patterns to subscribe to; an empty list is rejected

  • timeout (Float, Integer, nil) (defaults to: nil) —

    maximum time in seconds to wait for the server confirmation; nil blocks indefinitely

Raises:

  • (ArgumentError) —

    if timeout is negative

  • (Valkey::TimeoutError) —

    if the timeout expires before the server confirms

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



91
92
93
# File 'lib/valkey/commands/pubsub_commands.rb', line 91

def psubscribe(*patterns, timeout: nil)
  @pubsub.psubscribe(*patterns, timeout: timeout)
end

#psubscribe_lazy(*patterns) ⇒ void

This method returns an undefined value.

Subscribe to channel patterns without waiting for the server to confirm.

The client subscribes asynchronously in the background.

Examples:

Subscribe and verify later

valkey.psubscribe_lazy("news.*")
valkey.get_subscriptions.actual_subscriptions[:pattern]
  # => ["news.*"]

Parameters:

  • patterns (Array<String>) —

    the glob-style patterns to subscribe to; an empty list is rejected

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



210
211
212
# File 'lib/valkey/commands/pubsub_commands.rb', line 210

def psubscribe_lazy(*patterns)
  @pubsub.psubscribe_lazy(*patterns)
end

#publish(message, channel, sharded: false) ⇒ Integer

Publish a message on a Pub/Sub channel.

This method aggregates the PUBLISH and SPUBLISH functionalities; the mode is selected with the sharded parameter. In both modes the request is routed using the hashed channel as key. The argument order is (message, channel), matching the other GLIDE clients.

Examples:

Publish a message

valkey.publish("Hello, World!", "channel1")
  # => 2

Publish on a sharded channel

valkey.publish("Hello, Shard!", "shard1", sharded: true)
  # => 1

Parameters:

  • message (String) —

    the message to publish

  • channel (String) —

    the channel to publish the message on

  • sharded (Boolean) (defaults to: false) —

    use sharded Pub/Sub mode; only available in cluster mode (cluster_mode: true). Since: Valkey version 7.0.0

Returns:

  • (Integer) —

    the number of subscriptions that received the message: in cluster mode the subscriptions on the node the request was routed to, in standalone the subscriptions on the primary node, which excludes subscriptions configured on replicas

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



293
294
295
# File 'lib/valkey/commands/pubsub_commands.rb', line 293

def publish(message, channel, sharded: false)
  @pubsub.publish(message, channel, sharded: sharded)
end

#pubsub_channels(pattern = nil) ⇒ Array<String>

List the currently active channels, that is, the channels with at least one subscriber.

In cluster mode the command is routed to all nodes and the responses are combined.

Examples:

List all active channels

valkey.pubsub_channels
  # => ["channel1", "channel2"]

List active channels matching a pattern

valkey.pubsub_channels("news.*")
  # => ["news.sports", "news.weather"]

Parameters:

  • pattern (String, nil) (defaults to: nil) —

    a glob-style pattern to match active channels against; if not provided, all active channels are returned

Returns:

  • (Array<String>) —

    the active channels matching the given pattern

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



358
359
360
# File 'lib/valkey/commands/pubsub_commands.rb', line 358

def pubsub_channels(pattern = nil)
  @pubsub.pubsub_channels(pattern)
end

#pubsub_numpat ⇒ Integer

Get the number of unique patterns that are subscribed to by clients.

In cluster mode the command is routed to all nodes and the counts are summed.

This is the total number of unique patterns all the clients are subscribed to, not the count of clients subscribed to patterns.

Examples:

Get the pattern count

valkey.pubsub_numpat
  # => 3

Returns:

  • (Integer) —

    the number of unique patterns

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



377
378
379
# File 'lib/valkey/commands/pubsub_commands.rb', line 377

def pubsub_numpat
  @pubsub.pubsub_numpat
end

#pubsub_numsub(*channels) ⇒ Hash{String => Integer}

Get the number of subscribers for the specified channels, exclusive of clients subscribed to patterns.

In cluster mode the command is routed to all nodes and the counts are combined.

Examples:

Get subscriber counts

valkey.pubsub_numsub("channel1", "channel2")
  # => {"channel1" => 5, "channel2" => 3}

Call it without channels

valkey.pubsub_numsub
  # => {}

Parameters:

  • channels (Array<String>) —

    the channels to query for the number of subscribers; an empty list returns an empty hash

Returns:

  • (Hash{String => Integer}) —

    the channel names mapped to their number of subscribers

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



398
399
400
# File 'lib/valkey/commands/pubsub_commands.rb', line 398

def pubsub_numsub(*channels)
  @pubsub.pubsub_numsub(*channels)
end

#pubsub_shardchannels(pattern = nil) ⇒ Array<String>

List the currently active sharded channels, that is, the ones with at least one subscriber.

In cluster mode the command is routed to all nodes and the responses are combined.

Only available in cluster mode (cluster_mode: true). Since: Valkey version 7.0.0.

Examples:

List all active shard channels

valkey.pubsub_shardchannels
  # => ["shard1", "shard2"]

List active shard channels matching a pattern

valkey.pubsub_shardchannels("shard.*")
  # => ["shard.1", "shard.2"]

Parameters:

  • pattern (String, nil) (defaults to: nil) —

    a glob-style pattern to match active sharded channels against; if not provided, all active sharded channels are returned

Returns:

  • (Array<String>) —

    the active sharded channels matching the given pattern

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



421
422
423
# File 'lib/valkey/commands/pubsub_commands.rb', line 421

def pubsub_shardchannels(pattern = nil)
  @pubsub.pubsub_shardchannels(pattern)
end

#pubsub_shardnumsub(*channels) ⇒ Hash{String => Integer}

Get the number of subscribers for the specified sharded channels, exclusive of clients subscribed to patterns.

Only available in cluster mode (cluster_mode: true). Since: Valkey version 7.0.0.

Examples:

Get shard subscriber counts

valkey.pubsub_shardnumsub("shard1", "shard2")
  # => {"shard1" => 2, "shard2" => 1}

Call it without channels

valkey.pubsub_shardnumsub
  # => {}

Parameters:

  • channels (Array<String>) —

    the sharded channels to query for the number of subscribers; an empty list returns an empty hash

Returns:

  • (Hash{String => Integer}) —

    the sharded channel names mapped to their number of subscribers

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



443
444
445
# File 'lib/valkey/commands/pubsub_commands.rb', line 443

def pubsub_shardnumsub(*channels)
  @pubsub.pubsub_shardnumsub(*channels)
end

#punsubscribe(*patterns, timeout: nil) ⇒ void

This method returns an undefined value.

Unsubscribe from channel patterns, waiting for the server to confirm the change.

Examples:

Unsubscribe from patterns

valkey.punsubscribe("news.*", "events.*")

Unsubscribe from every subscribed pattern

valkey.punsubscribe

Parameters:

  • patterns (Array<String>) —

    the patterns to unsubscribe from; an empty list unsubscribes from all patterns

  • timeout (Float, Integer, nil) (defaults to: nil) —

    maximum time in seconds to wait for the server confirmation; nil blocks indefinitely

Raises:

  • (ArgumentError) —

    if timeout is negative

  • (Valkey::TimeoutError) —

    if the timeout expires before the server confirms

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



112
113
114
# File 'lib/valkey/commands/pubsub_commands.rb', line 112

def punsubscribe(*patterns, timeout: nil)
  @pubsub.punsubscribe(*patterns, timeout: timeout)
end

#punsubscribe_lazy(*patterns) ⇒ void

This method returns an undefined value.

Unsubscribe from channel patterns without waiting for the server to confirm.

Examples:

Unsubscribe and verify later

valkey.punsubscribe_lazy("news.*")
valkey.get_subscriptions.actual_subscriptions[:pattern]
  # => []

Parameters:

  • patterns (Array<String>) —

    the patterns to unsubscribe from; an empty list unsubscribes from all patterns

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



227
228
229
# File 'lib/valkey/commands/pubsub_commands.rb', line 227

def punsubscribe_lazy(*patterns)
  @pubsub.punsubscribe_lazy(*patterns)
end

#ssubscribe(*channels, timeout: nil) ⇒ void

This method returns an undefined value.

Subscribe to sharded channels, waiting for the server to confirm the subscription.

Only available in cluster mode (cluster_mode: true). Since: Valkey version 7.0.0.

Examples:

Subscribe to shard channels

valkey.ssubscribe("shard1", "shard2")

Give up if the server does not confirm within 2 seconds

valkey.ssubscribe("shard1", timeout: 2)

Parameters:

  • channels (Array<String>) —

    the sharded channels to subscribe to; an empty list is rejected

  • timeout (Float, Integer, nil) (defaults to: nil) —

    maximum time in seconds to wait for the server confirmation; nil blocks indefinitely

Raises:

  • (ArgumentError) —

    if timeout is negative

  • (Valkey::TimeoutError) —

    if the timeout expires before the server confirms

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



134
135
136
# File 'lib/valkey/commands/pubsub_commands.rb', line 134

def ssubscribe(*channels, timeout: nil)
  @pubsub.ssubscribe(*channels, timeout: timeout)
end

#ssubscribe_lazy(*channels) ⇒ void

This method returns an undefined value.

Subscribe to sharded channels without waiting for the server to confirm.

The client subscribes asynchronously in the background. Only available in cluster mode (cluster_mode: true). Since: Valkey version 7.0.0.

Examples:

Subscribe and verify later

valkey.ssubscribe_lazy("shard1")
valkey.get_subscriptions.actual_subscriptions[:sharded]
  # => ["shard1"]

Parameters:

  • channels (Array<String>) —

    the sharded channels to subscribe to; an empty list is rejected

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



246
247
248
# File 'lib/valkey/commands/pubsub_commands.rb', line 246

def ssubscribe_lazy(*channels)
  @pubsub.ssubscribe_lazy(*channels)
end

#subscribe(*channels, timeout: nil) ⇒ void

This method returns an undefined value.

Subscribe to exact channels, waiting for the server to confirm the subscription.

Examples:

Subscribe to channels

valkey.subscribe("channel1", "channel2")

Give up if the server does not confirm within 2.5 seconds

valkey.subscribe("channel1", timeout: 2.5)

Parameters:

  • channels (Array<String>) —

    the channels to subscribe to; an empty list is rejected

  • timeout (Float, Integer, nil) (defaults to: nil) —

    maximum time in seconds to wait for the server confirmation; nil blocks indefinitely

Raises:

  • (ArgumentError) —

    if timeout is negative

  • (Valkey::TimeoutError) —

    if the timeout expires before the server confirms

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



50
51
52
# File 'lib/valkey/commands/pubsub_commands.rb', line 50

def subscribe(*channels, timeout: nil)
  @pubsub.subscribe(*channels, timeout: timeout)
end

#subscribe_lazy(*channels) ⇒ void

This method returns an undefined value.

Subscribe to exact channels without waiting for the server to confirm.

The client subscribes asynchronously in the background.

Examples:

Subscribe and verify later

valkey.subscribe_lazy("channel1", "channel2")
valkey.get_subscriptions.actual_subscriptions[:exact]
  # => ["channel1", "channel2"]

Parameters:

  • channels (Array<String>) —

    the channels to subscribe to; an empty list is rejected

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



175
176
177
# File 'lib/valkey/commands/pubsub_commands.rb', line 175

def subscribe_lazy(*channels)
  @pubsub.subscribe_lazy(*channels)
end

#sunsubscribe(*channels, timeout: nil) ⇒ void

This method returns an undefined value.

Unsubscribe from sharded channels, waiting for the server to confirm the change.

Only available in cluster mode (cluster_mode: true). Since: Valkey version 7.0.0.

Examples:

Unsubscribe from shard channels

valkey.sunsubscribe("shard1", "shard2")

Unsubscribe from every subscribed shard channel

valkey.sunsubscribe

Parameters:

  • channels (Array<String>) —

    the sharded channels to unsubscribe from; an empty list unsubscribes from all sharded channels

  • timeout (Float, Integer, nil) (defaults to: nil) —

    maximum time in seconds to wait for the server confirmation; nil blocks indefinitely

Raises:

  • (ArgumentError) —

    if timeout is negative

  • (Valkey::TimeoutError) —

    if the timeout expires before the server confirms

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



157
158
159
# File 'lib/valkey/commands/pubsub_commands.rb', line 157

def sunsubscribe(*channels, timeout: nil)
  @pubsub.sunsubscribe(*channels, timeout: timeout)
end

#sunsubscribe_lazy(*channels) ⇒ void

This method returns an undefined value.

Unsubscribe from sharded channels without waiting for the server to confirm.

Only available in cluster mode (cluster_mode: true). Since: Valkey version 7.0.0.

Examples:

Unsubscribe and verify later

valkey.sunsubscribe_lazy("shard1")
valkey.get_subscriptions.actual_subscriptions[:sharded]
  # => []

Parameters:

  • channels (Array<String>) —

    the sharded channels to unsubscribe from; an empty list unsubscribes from all sharded channels

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



265
266
267
# File 'lib/valkey/commands/pubsub_commands.rb', line 265

def sunsubscribe_lazy(*channels)
  @pubsub.sunsubscribe_lazy(*channels)
end

#try_get_pubsub_message ⇒ Valkey::Glide::PubSub::Message?

Get the next Pub/Sub message if one is already queued. Never blocks.

Examples:

Poll for a message

valkey.try_get_pubsub_message
  # => #<struct Valkey::Glide::PubSub::Message message="hi", channel="channel1", pattern=nil>

Poll when nothing is queued

valkey.try_get_pubsub_message
  # => nil

Returns:

  • (Valkey::Glide::PubSub::Message, nil) —

    the message, or nil when the queue is empty or the client is closed. #pattern is set only when the push was a PMESSAGE



321
322
323
# File 'lib/valkey/commands/pubsub_commands.rb', line 321

def try_get_pubsub_message
  @pubsub.try_get_message
end

#unsubscribe(*channels, timeout: nil) ⇒ void

This method returns an undefined value.

Unsubscribe from exact channels, waiting for the server to confirm the change.

Examples:

Unsubscribe from channels

valkey.unsubscribe("channel1", "channel2")

Unsubscribe from every subscribed channel

valkey.unsubscribe

Parameters:

  • channels (Array<String>) —

    the channels to unsubscribe from; an empty list unsubscribes from all exact channels

  • timeout (Float, Integer, nil) (defaults to: nil) —

    maximum time in seconds to wait for the server confirmation; nil blocks indefinitely

Raises:

  • (ArgumentError) —

    if timeout is negative

  • (Valkey::TimeoutError) —

    if the timeout expires before the server confirms

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



71
72
73
# File 'lib/valkey/commands/pubsub_commands.rb', line 71

def unsubscribe(*channels, timeout: nil)
  @pubsub.unsubscribe(*channels, timeout: timeout)
end

#unsubscribe_lazy(*channels) ⇒ void

This method returns an undefined value.

Unsubscribe from exact channels without waiting for the server to confirm.

Examples:

Unsubscribe and verify later

valkey.unsubscribe_lazy("channel1")
valkey.get_subscriptions.actual_subscriptions[:exact]
  # => ["channel2"]

Parameters:

  • channels (Array<String>) —

    the channels to unsubscribe from; an empty list unsubscribes from all exact channels

Raises:

  • (NotImplementedError) —

    this method is not implemented yet

See Also:



192
193
194
# File 'lib/valkey/commands/pubsub_commands.rb', line 192

def unsubscribe_lazy(*channels)
  @pubsub.unsubscribe_lazy(*channels)
end