CLIENT-UNBLOCK(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 CLIENT-UNBLOCK — the valkey command manual, bestie edition 💖

okay so this is a page from the Valkey Command Manual, and today's main character is CLIENT UNBLOCK. yes it's a 3valkey manual page, yes it's iconic, let's get into it 🫶

✨ NAME ✨

client-unblock — unblocks a client that's stuck blocked on a blocking command, and you do it from a whole different connection. sneaky? no. efficient? yes. 💅

✨ SYNOPSIS ✨

CLIENT UNBLOCK client-id [TIMEOUT | ERROR]

🦋 DESCRIPTION 🦋

So here's the tea: this command lets you reach over from another connection and free a client that's currently blocked inside a blocking operation. We're talking stuff like BRPOP from valkey-brpop(7), or XREAD from valkey-xread(7), or WAIT from valkey-wait(7). you know, the commands where a client just sits there vibing, waiting for something to happen 😭

By default, the client gets unblocked as if the timeout of the command was reached. that's the chill default. BUT if you pass that extra (and optional) argument, you get to pick the unblocking behavior yourself, and your choices are TIMEOUT (which is the default) or ERROR.

If you pick ERROR, the vibe flips: the client gets unblocked by being handed an error telling it that it was force-unblocked. Specifically, the client receives this:

-UNBLOCKED client unblocked via CLIENT UNBLOCK
Note bestie: as usual, it is not guaranteed that the error text stays exactly the same. but the error code will remain -UNBLOCKED, no cap. 👑

🌸 when is this actually useful 🌸

This command really shines when you're monitoring many keys but only have a limited number of connections. picture it: you wanna watch multiple streams with XREAD without ever using more than N connections. slay, fine. but then at some point the consumer process gets told there's one more stream key to monitor 🙈

To avoid burning extra connections, the best behavior is: stop the blocking command on one of the connections in the pool, add the new key, and then issue the blocking command again. chef's kiss, no extra connections needed. 🎀

🧚 the pattern (iykyk) 🧚

To get that behavior, here's the pattern:

  • The process keeps an extra control connection around specifically so it can send the CLIENT UNBLOCK command whenever it needs to.
  • Meanwhile, before running the blocking operation on the other connections, the process runs CLIENT ID from valkey-client-id(7) to grab the ID associated with that connection.
  • Then, when a new key should be added — or when a key should no longer be monitored — the relevant connection's blocking command gets aborted by sending CLIENT UNBLOCK over on the control connection.
  • The blocking command returns, and finally it can be reissued. 🌈

The example below shows this whole thing in the context of streams, but lowkey the pattern is a general one and can be applied to other cases too. it's giving "transferable skill". 💜

⭐ REPLY ⭐

You get one of these:

🔥 COMPLEXITY 🔥

O(log N) where N is the number of client connections. not bad, not bad at all. ✨

💅 ACL CATEGORIES 💅

@admin @connection @dangerous @slow

(yes it's @dangerous, it's got main character energy and it knows it.)

🎀 HISTORY 🎀

  • Available since: 5.0.0

🌈 EXAMPLES 🌈

Connection A (blocking connection):
> CLIENT ID
2934
> BRPOP key1 key2 key3 0
(client is blocked)

... Now we want to add a new key ...

Connection B (control connection):
> CLIENT UNBLOCK 2934
1

Connection A (blocking connection):
... BRPOP reply with timeout ...
NULL
> BRPOP key1 key2 key3 key4 0
(client is blocked again)

👑 SEE ALSO 👑

auth(3valkey), client(3valkey), client-caching(3valkey), client-capa(3valkey), client-getname(3valkey), client-getredir(3valkey), client-help(3valkey), client-id(3valkey), client-import-source(3valkey), client-info(3valkey), client-kill(3valkey), client-list(3valkey), client-no-evict(3valkey), client-no-touch(3valkey), client-pause(3valkey), client-reply(3valkey), client-setinfo(3valkey), client-setname(3valkey), client-tracking(3valkey), client-trackinginfo(3valkey), client-unpause(3valkey), echo(3valkey), hello(3valkey), ping(3valkey), quit(3valkey), reset(3valkey), select(3valkey)

and that's the whole page, bestie 🫶 this one's from version 9.0.0, dated 2025-10-21 — so yes, it's recent, it's fresh, it's eating. go unblock somebody (from a different connection, obviously). periodt. 💖✨

📦 where this page comes from