SHUTDOWN(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💅 SHUTDOWN — the valkey command manual, bestie edition

okay so real talk, this one's called shutdown and what it does is: it synchronously saves the database(s) to disk and shuts down the server. like, gracefully. no drama. (well, some drama, keep reading 🫶)

✨ SYNOPSIS ✨

SHUTDOWN [[NOSAVE | SAVE] [NOW] [FORCE] [SAFE] [FAILOVER] | ABORT]

🌸 DESCRIPTION 🌸

the way this command works is literally a whole little routine, and here's the order of operations, no skipping steps:

  • if there are any replicas lagging behind in replication:
    • it pauses clients attempting to write by performing a valkey-client-pause(7) CLIENT PAUSE with the WRITE option.
    • then it waits up to the configured shutdown-timeout (default 10 seconds, iconic) for replicas to catch up the replication offset.
  • it stops all the clients.
  • it performs a blocking SAVE if at least one save point is configured.
  • it flushes the Append Only File if AOF is enabled.
  • it quits the server. bye bestie 💖

if persistence is enabled, this command makes sure that Valkey is switched off without any data loss. no data left behind, periodt.

note: a Valkey instance that is configured for not persisting on disk (no AOF configured, nor "save" directive) will not dump the RDB file on SHUTDOWN, because usually you don't want Valkey instances that are used only for caching to block on when shutting down. cache girlies stay unbothered ✨

also note (yes there's a second one, she's thorough): if Valkey receives one of the signals SIGTERM and SIGINT, the same shutdown sequence is performed. see also valkey-signals(7) Signal Handling. 👑

🎀 Modifiers 🎀

you can specify optional modifiers to alter the behavior of the command. specifically:

  • SAVE will force a DB saving operation even if no save points are configured. 💾
  • NOSAVE will prevent a DB saving operation even if one or more save points are configured. 🚫
  • NOW skips waiting for lagging replicas, i.e. it bypasses the first step in the shutdown sequence. ⏩
  • FORCE ignores any errors that would normally prevent the server from exiting. for details, see the following section. 😤
  • SAFE will return an error if it is unsafe to shut down. for details, see the following section. 🛟
  • FAILOVER will trigger a failover before shutting down a primary node in a cluster. 🔄
  • ABORT cancels an ongoing shutdown and cannot be combined with other flags. 🙅♀️

💀 Conditions where a SHUTDOWN fails 💀

when a save point is configured or the SAVE modifier is specified, the shutdown may fail if the RDB file can't be saved. in that case the server just keeps running, so that no data is lost. this may be bypassed using the FORCE modifier, which causes the server to exit anyway. (yes, that's the "f around and find out" flag. it's giving dangerous. be careful.)

when the Append Only File is enabled the shutdown may fail because the system is in a state that does not allow to safely immediately persist on disk.

normally, if there is an AOF child process performing an AOF rewrite, Valkey will simply kill it and exit. however, there are situations where it is unsafe to do so and, unless the FORCE modifier is specified, the SHUTDOWN command will be refused with an error instead. this happens in the following situations:

  • the user just turned on AOF, and the server triggered the first AOF rewrite in order to create the initial AOF file. in this context, stopping will result in losing the dataset at all: once restarted, the server will potentially have AOF enabled without having any AOF file at all. 😭
  • a replica with AOF enabled, reconnected with its primary, performed a full resynchronization, and restarted the AOF file, triggering the initial AOF creation process. in this case, not completing the AOF rewrite is dangerous because the latest dataset received from the primary would be lost. the new primary can actually be even a different instance (if the valkey-replicaof(7) REPLICAOF or valkey-slaveof(7) SLAVEOF command was used in order to reconfigure the replica), so it is important to finish the AOF rewrite and start with the correct data set representing the data set in memory when the server was terminated. 🧠✨

when the SAFE modifier is specified, the shutdown may fail if the Valkey instance is in an unsafe situation. unless the FORCE modifier is specified, the SHUTDOWN command will be refused with an error instead. this happens in the following situations:

  • in cluster mode, if the instance is a primary node and is responsible for at least one slot, shutting down such a node will cause the cluster to fail, so SAFE will refuse to shut down. 💀

there are situations when we want just to terminate a Valkey instance ASAP, regardless of what its content is. in such a case, the command SHUTDOWN NOW NOSAVE FORCE can be used. in versions before 7.0, where the NOW and FORCE flags are not available, the right combination of commands is to send a valkey-config(7) CONFIG appendonly no followed by a SHUTDOWN NOSAVE. the first command will turn off the AOF if needed, and will terminate the AOF rewriting child if there is one active. the second command will not have any problem to execute since the AOF is no longer enabled. 🧚 (iykyk, legacy lore)

🌈 Minimize the risk of data loss 🌈

the server waits for lagging replicas up to a configurable shutdown-timeout, by default 10 seconds, before shutting down. this provides a best effort minimizing the risk of data loss in a situation where no save points are configured and AOF is disabled. before version 7.0, shutting down a heavily loaded primary node in a diskless setup was more likely to result in data loss. to minimize the risk of data loss in such setups, it's advised to trigger a manual valkey-failover(7) FAILOVER (or valkey-cluster-failover(7) CLUSTER FAILOVER) to demote the primary to a replica and promote one of the replicas to be the new primary, before shutting down a primary node. 🫶 that's just good hygiene bestie.

💌 REPLY 💌

valkey-protocol(7) Simple string reply: OK if ABORT was specified and shutdown was aborted. on successful shutdown, nothing is returned because the server quits and the connection is closed (it literally left the chat 😭). on failure, an error is returned.

⭐ COMPLEXITY ⭐

O(N) when saving, where N is the total number of keys in all databases when saving data, otherwise O(1)

👑 ACL CATEGORIES 👑

@admin @dangerous @slow

🦋 HISTORY 🦋

  • Available since: 1.0.0
  • Changed in 7.0.0: added the NOW, FORCE and ABORT modifiers.
  • Changed in 9.0.0: added the SAFE and FAILOVER modifiers.

🌸 SEE ALSO 🌸

and that's the whole page bestie!! this is version 9.0.0 of the Valkey Command Manual, dated 2025-10-21 — shoutout to SHUTDOWN(3valkey) for being the main character of this file. stay safe, save your data, don't raw-dog SHUTDOWN NOSAVE FORCE unless you truly mean it 💖✨

📦 where this page comes from