Migrate a key name
Change a cache key after a namespace or identifier migration without rewriting its stored value.
Redis · Command
RENAME
Renames a key to a new name, replacing the destination if it already exists. In Redis Cluster, both names must belong to the same hash slot.
- Since
- 1.0.0
How it works
RENAME moves an existing key from key to newkey and returns success. If the destination already exists, Redis replaces it; in clustered deployments, both names must map to the same hash slot.
Syntax
RENAME key newkeyParameters
| Name | Type | Description |
|---|---|---|
key | key | The key to rename. |
newkey | key | The new key name. An existing key with this name is overwritten. |
Returns
Simple string: OK on success; an error when the source key does not exist.
Key points
- The command transfers the key's existing value and associated data to the new name.
- A missing source key causes the command to fail rather than creating the destination.
- The destination name is not preserved when it already refers to another key.
- RENAME has been available since Redis Open Source 1.0.0.
- The documented normal-case complexity is constant time.
Common mistakes
- The destination is replaced without a protection check, so use RENAMENX when overwriting an existing destination would be unsafe.
- Replacing a large destination can trigger an implicit deletion and add latency.
- Cluster deployments require compatible hash slots, typically achieved by using the same hash tag in both names.
Example: Rename a key
SET user:42 "Ada"
RENAME user:42 user:99
GET user:99Stores a value, moves the key to a new name, then reads it through the new name.
When to use it
Promote staged data
Publish a completed temporary value under its final key name.
Cluster-compatible renaming
Move a key within a cluster when both names share a hash tag and slot.
Interview questions
QWhat does RENAME do when the source key is missing?
RENAME changes the name of an existing key and returns a simple string success response. If the source key does not exist, Redis returns an error.
Follow-up: What happens when the destination exists? Redis overwrites it through an implicit DEL, which can add latency for a very large value.
QWhat is RENAME's time complexity, and what performance caveat applies?
The command has O(1) time complexity in the usual case. However, replacing an existing destination can incur deletion work that is not represented by the nominal rename complexity.
Follow-up: How would you avoid an unconditional overwrite? Use RENAMENX, which renames only when the target name does not already exist.
QWhat restriction applies to RENAME in cluster mode?
In Redis Cluster, the source and destination must be assigned to the same hash slot. Keys using the same hash tag can be designed to satisfy that requirement.
Follow-up: Why does this matter? Multi-key operations cannot reliably coordinate keys placed in different cluster slots.
Related
DELRENAMENXCOPYCOMMAND GETKEYS