CLIENT-PAUSE(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 CLIENT-PAUSE 💖

okay bestie, so this one lives in the valkey command manual (that's the 3valkey manual, section 3, iykyk) and it's literally the "everybody freeze" button 🧊✨

✨ NAME ✨

client-pause — Suspends commands processing. that's it. that's the whole job. it pauses. the processing. of commands. 💅

🌸 SYNOPSIS 🌸

CLIENT PAUSE timeout [WRITE | ALL]

🦋 DESCRIPTION 🦋

So CLIENT PAUSE is a connections control command, and what it does is suspend all the Valkey clients for however long you tell it to (the time is in milliseconds, jsyk ⏱️).

Here's the whole rundown of what it actually does, no cap:

  • It stops processing all the pending commands from normal and pub/sub clients — but only for the given mode. Interactions with replicas keep going like normal though, they're not affected. also lowkey important: clients are formally paused when they try to execute a command, so the server isn't doing any work for clients that are just sitting there inactive. slay, efficient.
  • BUT — and this is the iconique part — it returns OK to the caller ASAP. so the CLIENT PAUSE command's own execution is not paused by itself. main character behavior honestly.
  • And when the amount of time you specified has elapsed, all the clients get unblocked: that triggers the processing of all the commands that piled up in every client's query buffer during the pause. the floodgates open 💧

Client pause currently supports two modes:

  • ALL: This is the default mode. All client commands are blocked. every single one. no exceptions.
  • WRITE: Clients are only blocked if they attempt to execute a write command. so reads can still go off.

And for the WRITE mode, some commands have special behavior — pay attention bestie, this is the part that trips people up:

  • EVAL/EVALSHA: Will block client for all scripts.
  • PUBLISH: Will block client.
  • PFCOUNT: Will block client.
  • WAIT/WAITAOF: Acknowledgments will be delayed, so these commands will appear blocked.

🎀 why you'd even use this 🎀

This command is useful because it makes it able to switch clients from a Valkey instance to another one in a controlled way. like, actually controlled, not vibes-based. for example, during an instance upgrade the system administrator could do the following:

  1. Pause the clients using CLIENT PAUSE
  2. Wait a few seconds to make sure the replicas processed the latest replication stream from the primary.
  3. Turn one of the replicas into a primary.
  4. Reconfigure clients to connect with the new primary.

The recommended mode for client pause is WRITE. This mode will stop all replication traffic, can be aborted with the valkey-client-unpause(7) CLIENT UNPAUSE command, and allows reconfiguring the old primary without risking accepting writes after the failover. This is also the mode used during cluster failover. so like… it's the moment, fr fr 👑

This command also prevents keys to be evicted or expired during the time clients are paused. This way the dataset is guaranteed to be static — not just from the point of view of clients not being able to write, but also from the point of view of internal operations. everything frozen. nothing moving. the dataset is in its ✨stillness era✨

💬 REPLY 💬

valkey-protocol(7) Simple string reply: OK or an error if the timeout is invalid. so like, give it a bad timeout and it will read you to filth 😭

⚡ COMPLEXITY ⚡

O(1)

🔐 ACL CATEGORIES 🔐

@admin @connection @dangerous @slow

📜 HISTORY 📜

  • Available since: 3.0.0
  • Changed in 6.2.0: CLIENT PAUSE WRITE mode added along with the mode option.

👀 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-reply(3valkey), client-setinfo(3valkey), client-setname(3valkey), client-tracking(3valkey), client-trackinginfo(3valkey), client-unblock(3valkey), client-unpause(3valkey), echo(3valkey), hello(3valkey), ping(3valkey), quit(3valkey), reset(3valkey), select(3valkey)

k that's the whole page bestie 💖 go pause something responsibly, and remember: WRITE mode is the recommended one, not that I'm telling you what to do, but I am 🫶

Version 9.0.0 · 2025-10-21 · CLIENT-PAUSE(3valkey) — mwah, catch you in the next manpage 🌈⭐💜

📦 where this page comes from