Conditional initialization
Prevent a one-time initialization value from being overwritten when multiple clients race to create the same key.
Redis · Module
SETNX
Sets a string value only when a key does not already exist. It returns 1 when the key is created and 0 when no write occurs; SET with NX is the recommended replacement for new code.
- Since
- 2.0.0
How it works
SETNX attempts to store a string value only when the named key is absent. It performs no write when the key already exists and reports whether the write occurred with an integer result.
Syntax
SETNX key valueParameters
| Name | Type | Description |
|---|---|---|
key | key | The name of the key. |
value | string | The value to set, only if the key does not already exist. |
Returns
Integer reply: 1 if the key was set; 0 if the key was not set.
Key points
- It conditionally creates a key with a string value.
- An existing key remains unchanged, including its current value.
- The name describes its set-if-absent semantics.
- The integer result is 0 when the conditional write does not happen.
- The integer result is 1 when the command creates the key.
- The historical locking pattern stores a future validity timestamp as the lock value.
Common mistakes
- SETNX is deprecated; for new code, prefer SET with the NX option.
- A lock implemented with SETNX requires an explicit DEL release step, so the lock key must be managed carefully.
Example: Set only when absent
SETNX mykey "Hello"
SETNX mykey "World"
GET mykeyThe first command creates the key and returns 1; the second does nothing and returns 0, so GET still returns Hello.
When to use it
Simple locking primitive
Claim a key as a basic coordination marker so only the client receiving 1 proceeds.
Duplicate detection
Use the return code to distinguish the first insertion from later duplicate attempts.
Interview questions
QWhat does SETNX do?
SETNX stores the supplied string only if the key does not exist. It returns 1 when it creates the key and 0 when the key already exists.
Follow-up: How should new code express the same condition? Use SET with the NX option, which is the documented replacement for SETNX.
QWhat are SETNX's arguments and behavior when the key already exists?
The command takes exactly a key and a value: SETNX key value. The value is written only when the key is absent; an existing key is left unchanged.
Follow-up: What happens if the existing key contains a different data type? SETNX performs a presence check and does not replace the existing value.
QHow has SETNX historically been used for locking?
A successful result of 1 indicates that the client acquired the lock key; a result of 0 means another client already holds it. The documented pattern releases the lock with DEL.
Follow-up: What limitation should be considered for a production lock? A robust design needs an expiration and ownership-safe release strategy rather than relying only on a bare SETNX key.
Related
SETGETDEL