WAIT(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 WAIT (3valkey) 💖

okay bestie, this is the manual page for wait — a Valkey command, sitting pretty in section 3 of the manual. she's giving synchronization icon and honestly? we're obsessed. 🫶

✨ NAME ✨

wait — blocks until the asynchronous replication of all preceding write commands sent by the connection is completed. like, she will literally sit there and WAIT (hence the name, no cap). 💅

✨ SYNOPSIS ✨

WAIT numreplicas timeout

✨ DESCRIPTION ✨

so basically, this command blocks the current client until all the previous write commands are successfully transferred and acknowledged by at least the specified number of replicas. at least, okay? she's not greedy.

If the timeout — which is specified in milliseconds — is reached, the command returns even if the specified number of replicas were not yet reached. she's patient but not that patient. 😭

The command will always return the number of replicas that acknowledged the write commands sent by the current client before the WAIT command — both in the case where the specified number of replicas are reached, or when the timeout is reached. either way you're getting a number back, periodt. ✨

A few remarks, and bestie please read these, they're important:

  1. When WAIT returns, all the previous write commands sent in the context of the current connection are guaranteed to be received by the number of replicas returned by WAIT.
  2. If the command is sent as part of any context that does not allow blocking, such as inside scripts, the command does not block but instead just return ASAP the number of replicas that acknowledged the previous write commands. (so no main character blocking moment inside a script, she just answers and dips 💨)
  3. A timeout of 0 means to block forever. yes fr fr. forever forever. 🙈
  4. Since WAIT returns the number of replicas reached both in case of failure and success, the client should check that the returned value is equal or greater to the replication level it demanded. do the math yourself, bestie, she's not gonna do it for you 🧚

🦋 Consistency and WAIT 🦋

Note that WAIT does not make Valkey a strongly consistent store: while synchronous replication is part of a replicated state machine, it is not the only thing needed. so like, don't come for her, she's doing her part. 💜

However, in the context of Sentinel or Valkey Cluster failover, WAIT improves the real world data safety. that's the vibe check she passes. 🔥

Specifically, if a given write is transferred to one or more replicas, it is more likely (but not guaranteed) that if the primary fails, we'll be able to promote, during a failover, a replica that received the write: both Sentinel and Valkey Cluster will do a best-effort attempt to promote the best replica among the set of available replicas. best-effort is the key phrase here, queen.

However this is just a best-effort attempt so it is possible to still lose a write synchronously replicated to multiple replicas. 😭 yeah. she said it. it's real.

🧚 Implementation details 🧚

Since the introduction of partial resynchronization with replicas (PSYNC feature), Valkey replicas asynchronously ping their primary with the offset they already processed in the replication stream. This is used in multiple ways:

  1. Detect timed out replicas.
  2. Perform a partial resynchronization after a disconnection.
  3. Implement WAIT.

In the specific case of the implementation of WAIT, Valkey remembers, for each client, the replication offset of the produced replication stream when a given write command was executed in the context of a given client. When WAIT is called, Valkey checks if the specified number of replicas already acknowledged this offset or a greater one. bookkeeping but make it iconic ✨

✨ REPLY ✨

valkey-protocol(7) Integer reply: the number of replicas reached by all the writes performed in the context of the current connection.

✨ COMPLEXITY ✨

O(1) — she's fast, she's efficient, she's that girl. 💅

✨ ACL CATEGORIES ✨

@blocking @connection @slow

✨ HISTORY ✨

  • Available since: 3.0.0 — an OG, honestly. 👑

✨ EXAMPLES ✨

> SET foo bar
OK
> WAIT 1 0
(integer) 1
> WAIT 2 1000
(integer) 1

In the following example the first call to WAIT does not use a timeout and asks for the write to reach 1 replica. It returns with success. 🎀 In the second attempt instead we put a timeout, and ask for the replication of the write to two replicas. Since there is a single replica available, after one second WAIT unblocks and returns 1, the number of replicas reached. she tried her best and 1 out of 2 is still a number, bestie. 🫶

✨ SEE ALSO ✨

copy(3valkey), del(3valkey), dump(3valkey), exists(3valkey), expire(3valkey), expireat(3valkey), expiretime(3valkey), keys(3valkey), migrate(3valkey), move(3valkey), object(3valkey), object-encoding(3valkey), object-freq(3valkey), object-help(3valkey), object-idletime(3valkey), object-refcount(3valkey), persist(3valkey), pexpire(3valkey), pexpireat(3valkey), pexpiretime(3valkey), pttl(3valkey), randomkey(3valkey), rename(3valkey), renamenx(3valkey), restore(3valkey), scan(3valkey), sort(3valkey), sort_ro(3valkey), touch(3valkey), ttl(3valkey), type(3valkey), unlink(3valkey), waitaof(3valkey)

and that's the whole page, bestie!! 🌈 this one comes from Valkey version 9.0.0, dated 2025-10-21 — write that down, iykyk. mwah, go replicate responsibly 💋✨

📦 where this page comes from