VALKEY-PUBSUB(7)

💖 valkey-pubsub — Pub/Sub 💖

okay bestie, welcome to the valkey-pubsub manual page, a whole section of the Valkey manual, and it's giving "group chat for your servers" energy. let's get into it 🫶

---

✨ NAME ✨

valkey-pubsub — Pub/Sub, aka the part of Valkey where everybody's just talking and nobody's keeping receipts. 💬

---

🌸 DESCRIPTION 🌸

so like. SUBSCRIBE, UNSUBSCRIBE and PUBLISH implement the Publish/Subscribe messaging paradigm, where publishers send their messages to channels, with zero knowledge of what receivers (subscribers) might be out there. and subscribers? they express interest in one or more channels and only receive the messages that are of interest to them, also with zero knowledge of what (if any) publishers exist. it's giving mutual mystery. it's giving no strings attached. 💅

this decoupling of publishers and subscribers is what allows for greater scalability and a more dynamic network topology. slay.

big yikes alert: pubsub channels are not persisted. if there are no subscribers to a channel when a message is published, that message is gone. lost. evaporated. 💀 if you're looking for persisted message queues, you may want to look into valkey-streams-intro(7) Streams instead. (streams keep receipts. pubsub does not.)

to subscribe to channels "channel11" and "ch:00", the client issues a SUBSCRIBE providing the names of the channels:

SUBSCRIBE channel11 ch:00

messages sent by other clients to these channels will be pushed by Valkey to all the subscribed clients. and subscribers receive the messages in the order that the messages are published. no queue-jumping, we love an orderly line ✨

so here's the tea: a client subscribed to one or more channels shouldn't issue commands, although it can SUBSCRIBE and UNSUBSCRIBE to and from other channels. the replies to subscription and unsubscribing operations are sent in the form of messages, so the client can just read a coherent stream of messages where the first element indicates the type of message. iconic design honestly.

the commands that are allowed in the context of a subscribed RESP2 client are:

• PING
• PSUBSCRIBE
• PUNSUBSCRIBE
• QUIT
• RESET
• SSUBSCRIBE
• SUBSCRIBE
• SUNSUBSCRIBE
• UNSUBSCRIBE

but — plot twist — if RESP3 is used (see HELLO), a client can issue any commands while in the subscribed state. main character privileges fr fr 👑

please note that when using valkey-cli, in subscribed mode commands such as UNSUBSCRIBE and PUNSUBSCRIBE cannot be used, because valkey-cli will not accept any commands and can only quit the mode with Ctrl-C. 😭 so don't come for valkey-cli, it's just like that.

---

💌 Delivery semantics 💌

Valkey' Pub/Sub exhibits at-most-once message delivery semantics. as the name suggests, it means that a message will be delivered once if at all. once the message is sent by the Valkey server, there's no chance of it being sent again. if the subscriber is unable to handle the message (for example, due to an error or a network disconnect) the message is forever lost. forever. gone. 🪦

if your application requires stronger delivery guarantees, you may want to learn about valkey-streams-intro(7) Streams. messages in streams are persisted, and support both at-most-once as well as at-least-once delivery semantics. so if you need the message to show up no matter what, that's your girl.

---

📬 Format of pushed messages 📬

a message is an valkey-protocol(7) array-reply with three elements.

the first element is the kind of message:

• subscribe: means that we successfully subscribed to the channel given as the second element in the reply. the third argument represents the number of channels we are currently subscribed to.
• unsubscribe: means that we successfully unsubscribed from the channel given as second element in the reply. the third argument represents the number of channels we are currently subscribed to. when the last argument is zero, we are no longer subscribed to any channel, and the client can issue any kind of Valkey command as we are outside the Pub/Sub state. freedom!! 🦋
• message: it is a message received as a result of a PUBLISH command issued by another client. the second element is the name of the originating channel, and the third argument is the actual message payload.

---

🗂️ Database & Scoping 🗂️

Pub/Sub has no relation to the key space. it was made to not interfere with it on any level, including database numbers. truly minding its own business.

publishing on db 10, will be heard by a subscriber on db 1. yeah. that's just how it is. 🤷

if you need scoping of some kind, prefix the channels with the name of the environment (test, staging, production...). that's the move, bestie.

---

🔌 Wire protocol example 🔌

SUBSCRIBE first second
*3
$9
subscribe
$5
first
:1
*3
$9
subscribe
$6
second
:2

at this point, from another client we issue a PUBLISH operation against the channel named second:

> PUBLISH second Hello

this is what the first client receives:

*3
$7
message
$6
second
$5
Hello

now the client unsubscribes itself from all the channels using the UNSUBSCRIBE command without additional arguments:

UNSUBSCRIBE
*3
$11
unsubscribe
$6
second
:1
*3
$11
unsubscribe
$5
first
:0

and that's the whole arc. beginning, middle, unsubscribe. 🎬

---

🎀 Pattern-matching subscriptions 🎀

the Valkey Pub/Sub implementation supports pattern matching. clients may subscribe to glob-style patterns to receive all the messages sent to channel names matching a given pattern. it's giving ✨ selective hearing ✨

for instance:

PSUBSCRIBE news.*

will receive all the messages sent to the channel news.art.figurative, news.music.jazz, etc. all the glob-style patterns are valid, so multiple wildcards are supported. go wild (pun intended).

PUNSUBSCRIBE news.*

will then unsubscribe the client from that pattern. no other subscriptions will be affected by this call. so calm down, your other channels are fine 💖

messages received as a result of pattern matching are sent in a different format:

• the type of the message is pmessage: it is a message received as a result from a PUBLISH command issued by another client, matching a pattern-matching subscription. the second element is the original pattern matched, the third element is the name of the originating channel, and the last element is the actual message payload.

similarly to SUBSCRIBE and UNSUBSCRIBE, PSUBSCRIBE and PUNSUBSCRIBE commands are acknowledged by the system sending a message of type psubscribe and punsubscribe using the same format as the subscribe and unsubscribe message format.

---

👯 Messages matching both a pattern and a channel subscription 👯

a client may receive a single message multiple times if it's subscribed to multiple patterns matching a published message, or if it is subscribed to both patterns and channels matching the message. not a bug, it's a feature, and it's shown by the following example:

SUBSCRIBE foo
PSUBSCRIBE f*

in the above example, if a message is sent to channel foo, the client will receive two messages: one of type message and one of type pmessage. double texted. on purpose. 📲📲

---

🔢 The meaning of the subscription count with pattern matching 🔢

in subscribe, unsubscribe, psubscribe and punsubscribe message types, the last argument is the count of subscriptions still active. this number is the total number of channels and patterns the client is still subscribed to. so the client will exit the Pub/Sub state only when this count drops to zero as a result of unsubscribing from all the channels and patterns. zero or you're still in it. periodt. 💅

---

🧩 Sharded Pub/Sub 🧩

from Redis OSS 7.0, sharded Pub/Sub is introduced, in which shard channels are assigned to slots by the same algorithm used to assign keys to slots. a shard message must be sent to a node that owns the slot the shard channel is hashed to. the cluster makes sure the published shard messages are forwarded to all nodes in the shard, so clients can subscribe to a shard channel by connecting to either the primary responsible for the slot, or to any of its replicas. SSUBSCRIBE, SUNSUBSCRIBE and SPUBLISH are used to implement sharded Pub/Sub.

sharded Pub/Sub helps to scale the usage of Pub/Sub in cluster mode. it restricts the propagation of messages to be within the shard of a cluster. hence, the amount of data passing through the cluster bus is limited in comparison to global Pub/Sub where each message propagates to each node in the cluster. this allows users to horizontally scale the Pub/Sub usage by adding more shards. scaling era 🔥

---

🧚 Client library implementation hints 🧚

because all the messages received contain the original subscription causing the message delivery (the channel in the case of message type, and the original pattern in the case of pmessage type) client libraries may bind the original subscription to callbacks (that can be anonymous functions, blocks, function pointers), using a hash table.

when a message is received an O(1) lookup can be done to deliver the message to the registered callback. O(1)?? we love a constant-time queen 👑

---

and that's the whole page bestie!! 💖✨🎀🦋🌸

this was the VALKEY-PUBSUB(7) page from the Valkey 9.0.0 manual, dated 2025-10-21. go subscribe to something, text your friends back, and remember: if nobody's listening, that message is lost. 😭💜